Environments

You can configure environments with protection rules and secrets. A workflow job can reference an environment to use the environment's protection rules and secrets.

Environments, environment protection rules, and environment secrets are available in public repositories for all products. For access to environments in private repositories, you must use GitHub Enterprise. For more information, see "GitHub's products."

About environments

You can configure environments with protection rules and secrets. When a workflow job references an environment, the job won't start until all of the environment's protection rules pass. A job also cannot access secrets that are defined in an environment until all the environment protection rules pass.

Environment protection rules and environment secrets are only available on private repositories with GitHub Enterprise Cloud. For more information about how you can try GitHub Enterprise Cloud for free, see "Setting up a trial of GitHub Enterprise Cloud."

If you don't use GitHub Enterprise Cloud and convert a repository from public to private, any configured protection rules or environment secrets will be ignored, and you will not be able to configure any environments. If you convert your repository back to public, you will have access to any previously configured protection rules and environment secrets.

Environment protection rules

Environment protection rules require specific conditions to pass before a job referencing the environment can proceed. You can use environment protection rules to require a manual approval, delay a job, or restrict the environment to certain branches.

Required reviewers

Use required reviewers to require a specific person or team to approve workflow jobs that reference the environment. You can list up to six users or teams as reviewers. The reviewers must have at least read access to the repository. Only one of the required reviewers needs to approve the job for it to proceed.

For more information on reviewing jobs that reference an environment with required reviewers, see "Reviewing deployments."

Wait timer

Use a wait timer to delay a job for a specific amount of time after the job is initially triggered. The time (in minutes) must be an integer between 0 and 43,200 (30 days).

Deployment branches

Use deployment branches to restrict which branches can deploy to the environment. Below are the options for deployment branches for an environment:

  • All branches: All branches in the repository can deploy to the environment.

  • Protected branches: Only branches with branch protection rules enabled can deploy to the environment. If no branch protection rules are defined for any branch in the repository, then all branches can deploy. For more information about branch protection rules, see "About protected branches."

  • Selected branches: Only branches that match your specified name patterns can deploy to the environment.

    For example, if you specify releases/* as a deployment branch rule, only branches whose name begins with releases/ can deploy to the environment. (Wildcard characters will not match /. To match branches that begin with release/ and contain an additional single slash, use release/*/*.) If you add main as a deployment branch rule, a branch named main can also deploy to the environment. For more information about syntax options for deployment branches, see the Ruby File.fnmatch documentation.

Environment secrets

Secrets stored in an environment are only available to workflow jobs that reference the environment. If the environment requires approval, a job cannot access environment secrets until one of the required reviewers approves it. For more information about secrets, see "Encrypted secrets."

Note: Workflows that run on self-hosted runners are not run in an isolated container, even if they use environments. Environment secrets should be treated with the same level as security as repository and organization secrets. For more information, see "Security hardening for GitHub Actions."

Creating an environment

To configure an environment in a user account repository, you must be the repository owner. To configure an environment in an organization repository, you must have admin access.

  1. On GitHub, navigate to the main page of the repository.
  2. Under your repository name, click Settings. Repository settings button
  3. In the left sidebar, click Environments.
  4. Click New environment.
  5. Enter a name for the environment, then click Configure environment. Environment names are not case sensitive. An environment name may not exceed 255 characters and must be unique within the repository.
  6. Configure any environment protection rules or environment secrets.

You can also create and configure environments through the REST API. For more information, see "Environments" and "Secrets."

Running a workflow that references an environment that does not exist will create an environment with the referenced name. The newly created environment will not have any protection rules or secrets configured. Anyone that can edit workflows in the repository can create environments via a workflow file, but only repository admins can configure the environment.

Referencing an environment

Each job in a workflow can reference a single environment. Any protection rules configured for the environment must pass before a job referencing the environment is sent to a runner. When the job is sent to the runner, the job can access the environment's secrets.

For more information on syntax to reference environments in workflows, see "Workflow syntax for GitHub Actions." For more information on reviewing jobs that reference an environment with required reviewers, see "Reviewing deployments."

When a workflow references an environment, the environment will appear in the repository's deployments. For more information about viewing current and previous deployments, see "Viewing deployment history."

Using concurrency to serialize deployments in an environment

You can use concurrency so that an environment has a maximum of one deployment in progress and one deployment pending at a time. For more information, see "Workflow syntax for GitHub Actions."

Deleting an environment

To configure an environment in a user account repository, you must be the repository owner. To configure an environment in an organization repository, you must have admin access.

Deleting an environment will delete all secrets and protection rules associated with the environment. Any jobs currently waiting because of protection rules from the deleted environment will automatically fail.

  1. On GitHub, navigate to the main page of the repository.
  2. Under your repository name, click Settings. Repository settings button
  3. In the left sidebar, click Environments.
  4. Next to the environment that you want to delete, click .
  5. Click I understand, delete this environment.

You can also delete environments through the REST API. For more information, see "Environments."

Did this doc help you?Privacy policy

Help us make these docs great!

All GitHub docs are open source. See something that's wrong or unclear? Submit a pull request.

Make a contribution

Or, learn how to contribute.