gh-variable

List variables for the current repository

$ gh variable [[ls|list]]

$ gh variable [[ls|list]] [[-o|--org]] [organization]

$ gh variable get [name]

$ gh variable set [name]

$ gh variable set [name] [[-e|--env]] [environment_name]

$ gh variable set [name] [[-o|--org]] [organization] [[-v|--visibility]] all

$ gh variable set [[-f|--env-file]] [path/to/file.env]

$ gh variable delete [name]

The gh variable command group allows managing GitHub Actions variables.

General Syntax:
gh variable <command> [flags]

Subcommand Examples:
gh variable list [--repo <repo> | --org <org> | --env <environment_name>] [flags]
gh variable set <name> [--body <value>] [--repo <repo> | --org <org> | --env <environment_name>] [--visibility <all|private|selected>] [flags]
gh variable delete <name> [--repo <repo> | --org <org> | --env <environment_name>] [flags]

command
    The subcommand to execute within the gh variable group (e.g., list, set, delete).

<name>
    The required name of the variable to set or delete.

--body <value>
    The required value for the variable when using the set subcommand. Can also be read from standard input.

--repo <[HOST/]OWNER/REPO>
    Specify the target repository for the variable. Format: [HOST/]OWNER/REPO.

--org <organization>
    Specify the target organization for the variable.

--env <environment_name>
    Specify the target environment within a repository for the variable.

--visibility <all|private|selected>
    Set the visibility for an organization-level variable. Options: all repositories, private repositories, or selected repositories.

-h, --help
    Show help information for the command or subcommand.

--jq <expression>
    Filter JSON output using a jq expression.

--json <fields>
    Output JSON with a comma-separated selection of fields.

The gh variable command group, part of the GitHub CLI, provides tools to manage GitHub Actions variables. These variables are plain text key-value pairs that can be stored at the repository, organization, or environment level and made available to workflows. This command group offers functionalities to list existing variables, create or update variables with specific values, and delete them. It is an essential tool for automating the configuration of reusable values in CI/CD pipelines on GitHub, enabling consistent and dynamic workflow behavior directly from the command line.

Requires the GitHub CLI (gh) to be installed and authenticated to a GitHub account.
The user must possess appropriate permissions (e.g., 'admin' or 'write' access to repositories/organizations/environments) to manage variables.
Variables store plain text and are not suitable for sensitive information like API keys or tokens. For such data, use gh secret.
The --visibility flag is exclusively applicable when creating or updating organization-level variables.

Variables can be scoped to a specific repository, an entire organization, or a named environment within a repository. The chosen scope dictates where the variable is accessible and effective within GitHub Actions workflows.

When setting a variable, its value can be provided directly via the --body flag. Alternatively, for more complex or dynamically generated values, the content can be piped into the command from standard input (stdin), offering flexibility for scripting and automation.

The GitHub CLI (gh) was officially released in September 2020. The gh variable command group was introduced as part of the CLI's ongoing development to provide a comprehensive command-line interface for interacting with GitHub's features, including GitHub Actions. It aims to streamline automation and management of CI/CD resources directly from the terminal, enhancing developer productivity for GitHub users.

gh secret(1), gh workflow(1), gh env(1), jq(1)