Set GitHub Actions variables safely with gh variable set

You will create or update a GitHub Actions variable at repository, environment or organisation level, then check that it has the intended scope. Allow about ten minutes for one variable, provided you are already authenticated to GitHub and know the repository or organisation name.

This guide covers GitHub CLI 2.87.3, installed on this machine in February 2026. The command changes GitHub state remotely, so read the target name and scope before pressing Enter. A variable is not a secret: do not put passwords, tokens or private keys in it. Use gh secret set for sensitive values instead.

1. Check the CLI and authentication

Run these read-only checks first. The repository form uses the current directory's GitHub repository; use --repo OWNER/REPO when you want an explicit target.

$ gh --version
gh version 2.87.3
$ gh auth status
$ gh variable set --help

The installed command accepts --body, --env, --env-file, --org, --repos and --visibility. Authentication must include permission to administer variables at the selected level. No sudo is needed: this is a GitHub API operation, not a local system configuration change.

Checkpoint: target and value are clear

Before continuing, write down the variable name, its value, and where a workflow should read it. Repository variables are the default. Environment variables are tied to a deployment environment. Organisation variables can be available to the whole organisation or restricted to selected repositories.

2. Set a repository variable

Pass a non-sensitive value with --body. This example targets an explicitly named repository and records a build label:

$ gh variable set RELEASE_CHANNEL \
    --repo EXAMPLE_OWNER/EXAMPLE_REPO \
    --body 'stable'

The command creates the variable if it does not exist and updates it if it does. The remote value is changed immediately. The command normally produces no useful success text, so check the result explicitly:

$ gh variable get RELEASE_CHANNEL \
    --repo EXAMPLE_OWNER/EXAMPLE_REPO \
    --json name,value,visibility
{"name":"RELEASE_CHANNEL","value":"stable","visibility":"private"}

The exact JSON formatting can vary, but the name and value should match. If the command fails, keep the error text and exit status. A successful status is zero; authentication failures use the GitHub CLI exit-code conventions.

3. Set a deployment-environment variable

Use --env when the value belongs to a deployment environment rather than every workflow run in the repository:

$ gh variable set API_BASE_URL \
    --repo EXAMPLE_OWNER/EXAMPLE_REPO \
    --env staging \
    --body 'https://staging.example.invalid/api'

Keep the environment name exact. staging and Staging are different choices if your repository has both. Verify the environment scope with the matching read command:

$ gh variable get API_BASE_URL \
    --repo EXAMPLE_OWNER/EXAMPLE_REPO \
    --env staging \
    --json name,value

4. Import several values from a dotenv file

For a small group of ordinary configuration values, use --env-file. Create the file outside version control or review its contents first:

$ cat .env.actions
RELEASE_CHANNEL=stable
FEATURE_FLAG_NEW_UI=false
$ gh variable set --repo EXAMPLE_OWNER/EXAMPLE_REPO --env-file .env.actions

The file is input to a remote update. Treat every line as data that will become a variable, and do not include comments or values you would not want exposed to workflow users unless the installed CLI accepts the exact dotenv syntax you have tested. Check the resulting names without printing values:

$ gh variable list \
    --repo EXAMPLE_OWNER/EXAMPLE_REPO \
    --json name,visibility

5. Set an organisation variable deliberately

Organisation scope affects more repositories, so check the target twice. This makes a variable visible to public and private repositories in the organisation:

$ gh variable set RELEASE_CHANNEL \
    --org EXAMPLE_ORG \
    --visibility all \
    --body 'stable'

For a narrower audience, provide the repository names as a comma-separated list:

$ gh variable set INTERNAL_TOOLCHAIN \
    --org EXAMPLE_ORG \
    --repos platform-api,platform-web \
    --body 'v3'

Do not assume that a repository variable and an organisation variable with the same name are interchangeable. A workflow's context and GitHub's variable precedence determine which value it sees. Read the organisation value after setting it:

$ gh variable get INTERNAL_TOOLCHAIN \
    --org EXAMPLE_ORG \
    --json name,value,visibility,numSelectedRepos

6. Recover from a wrong value or scope

Updating is the same operation: rerun gh variable set with the correct scope and value. If you accidentally wrote a variable where it should not exist, stop any workflow that depends on it and remove it with the matching gh variable delete command after checking its help. Deletion is irreversible from the CLI, so preserve the intended value in a reviewed local note first if you may need to recreate it.

When a workflow still sees an old value, verify the exact repository, environment and organisation arguments before changing anything else. A successful update in one scope does not update a same-named variable in another scope.