GitHub Environments
Enable the Atmos Pro deployment protection rule and configure independent reviewer approvals for infrastructure changes.
Enable Atmos Pro in your GitHub environment's deployment protection rules to require an authorized Atmos Pro dispatch before a deployment starts. Add Required reviewers separately when you also want a human to approve the apply.
How deployment approvals work
Plan Requirements
Custom deployment protection
rules
require GitHub Enterprise for private or internal repositories. Required reviewers and wait timers are available in
public repositories across plans; branch/tag deployment restrictions are also available for private repositories on
GitHub Pro/Team/Enterprise. Without support for the custom rule, GitHub cannot request Atmos Pro approval. See the
non-Enterprise workflow pattern below.
Environments/Configure plat-prod
Deployment protection rules
Configure reviewers, timers, and custom rules that must pass before deployments to this environment can proceed.
Required reviewers
Specify people or teams that may approve workflow runs when they access this environment.
Add up to 5 more reviewers
Search for people or teams...
acme/managers
Prevent self-review
Require a different approver than the user who triggered the workflow run.
Wait timer
Set an amount of time to wait before allowing deployments to proceed.
Atmos Pro
Custom protection rule provided by Atmos Pro.
Enable additional custom rules with GitHub Apps Preview
Learn about existing apps or create your own protection rules so you can deploy with confidence.
Allow administrators to bypass configured protection rules
Deployment branches and tags
Limit which branches and tags can deploy to this environment.
1 branch and 0 tags allowed
mainCurrently applies to 1 branch
Add deployment branch or tag rule
Example settings. Make these changes in your repository on GitHub.
In your repository settings, navigate to Environments and create environments that match your deployment targets (e.g.,
production, staging, development). See Using environments for deployment in the GitHub docs for details.For each environment used by Atmos Pro that requires approval, configure deployment protection rules:
- 1Under Deployment protection rules, select the checkbox beside Atmos Pro, as shown above. Select the App connected to your Atmos Pro workspace; selecting a different App does not protect deployments through that workspace.
- 2Enable Required reviewers and add the individuals or teams who should approve deployments, if human approval is required. We recommend selecting Prevent self-review so the GitHub user who triggered the workflow cannot approve its deployment. Atmos Pro's custom rule does not approve on reviewers' behalf.
- 3Optionally configure a wait timer to add a delay before deployment.
- 4Clear Allow administrators to bypass configured protection rules if every deployment must pass the gates.
- 5Click Save protection rules.
- 6Under Deployment branches and tags, choose Selected branches and tags. Add a branch rule for
main, with no tag rules. For this production setup, GitHub should show 1 branch and 0 tags allowed, as illustrated above. If your repository's default dispatch branch is named differently, use that exact branch name instead. If you opt into Dispatch workflows from the PR branch in Atmos Pro repository settings, also allow the intended PR branches on environments used by those workflows. Amain-only environment deliberately rejects PR-branch dispatches. - 7In Atmos Pro, open Workspace → Repairs and select Recheck. A missing-rule finding resolves only after the correct enabled App rule is verified.
Repairs checks environments identified by literal
github_environment or environment inputs in recorded
Atmos workflows and enabled drift configuration, plus environments observed on jobs linked to this App's
recorded dispatches. It does not recommend locking unrelated GitHub Pages or Copilot environments to Atmos Pro.
If target discovery fails, Repairs reports the repository's status as unknown.Hardcoded or dynamically computed environments without a literal configuration input are discovered after
an Atmos-dispatched job reports them. Check their rules in GitHub before first use; an empty Repairs list
does not verify environments Atmos Pro has not discovered. This discovery scope does not limit the authorization
gate: every protection request from an environment with the Atmos Pro rule must pass its checks.
GitHub's self-review restriction applies to the workflow's triggering actor. For App-dispatched runs, it does not identify the person who requested the deployment through Atmos Pro.
Keep both restrictions: GitHub's selected-branch rule limits where the workflow is dispatched from, while the Atmos Pro rule verifies the recorded run and requested SHA. Allowing
main alone does not prove that inputs.sha belongs to it. The Atmos Pro gate authorizes branch dispatches, not tag dispatches.If Atmos Pro is not listed, confirm that the App is installed with access to this repository and that your GitHub plan supports custom deployment protection rules. A private or internal repository needs GitHub Enterprise. A permission error alone does not establish which plan you have.
An allowed branch is not enough
The protection webhook does not include workflow inputs. Atmos Pro records the exact
inputs.sha it sends when
dispatching, tied to the run ID returned by GitHub. The gate rejects runs with no matching record, including manual
GitHub or CLI dispatches from main. For recorded dispatches, it verifies that the environment permits the dispatch
branch and uses GitHub's commit comparison to verify that the requested SHA is contained in a branch permitted by
that environment. This check applies in both dispatch modes. An unmerged PR SHA is rejected by a main-only
environment even when Atmos Pro dispatched the workflow from main.Atmos Pro verifies the recorded dispatch SHA against the originating GitHub webhook event when evaluating
environment approval. Existing affected-stacks uploads and user-token authentication remain supported; accepting
an upload is not deployment authorization. Nested workflow
inputs.sha cannot override the server-selected
dispatch SHA, and uploaded metadata alone cannot satisfy the approval check. Scheduled drift and pinned
remediation commits are independently checked against the default branch through GitHub's authenticated API.
Missing or mismatched provenance rejects the protected deployment. Older dispatch records without source context
must be dispatched again.After a pull request merges,
inputs.sha is the commit that landed on the base branch: the squash commit, merge
commit, last rebased commit, or merge-queue commit that GitHub reports as the pull request's merge commit. It is
never the pull request's head, which a squash or rebase merge leaves off the base branch.PR dispatch policy is a repository setting
By default, PR workflows still run from the repository's default branch with the PR commit as
inputs.sha.
Use a separate planning environment that allows both the repository's default dispatch branch and the intended
PR branches. GitHub checks the workflow's dispatch ref independently; Atmos Pro also verifies that a permitted
branch contains the PR commit. A production environment restricted to main rejects unmerged PR code in either
mode. Manual dispatches remain rejected.Enable Dispatch workflows from the PR branch in Atmos Pro repository settings to use the PR branch's workflow
code and environment branch context instead. That branch must contain the workflow and be allowed by the environment.
The gate then requires the requested SHA to belong to the immutable dispatch branch snapshot. Fork PRs are unsupported
in this mode. Pinned approval previews also use the verified PR branch. Merge-queue workflows use the
GitHub-reported
gh-readonly-queue/… branch, which must contain the workflow and be allowed by the planning
environment. Post-merge workflows and scheduled drift still use the default branch with ancestry verification.
The repository dispatch policy is saved with each run. The environment's current restrictions are checked at approval
time against GitHub's current branch tips, independently of that saved policy.In your GitHub Actions workflow file, reference the environment in the job that runs
terraform apply:jobs:
apply:
runs-on: ubuntu-latest
environment: ${{ inputs.github_environment }}
steps:
- uses: actions/checkout@v6
with:
ref: ${{ inputs.sha }}
persist-credentials: false
- name: Apply
env:
COMPONENT: ${{ inputs.component }}
STACK: ${{ inputs.stack }}
run: atmos terraform deploy "${COMPONENT}" -s "${STACK}"Notice that
environment uses ${{ inputs.github_environment }} rather than a hardcoded value. Atmos Pro passes the environment name through from your stack configuration when it dispatches the workflow, so the same workflow file works across all your environments. The environment is configured in your Atmos stack YAML — not in the workflow itself — which means you can dynamically target different GitHub environments based on the stack being deployed.Declare
sha and github_environment as workflow inputs as described in Configure workflows. When Atmos Pro dispatches this workflow, GitHub waits for the Atmos Pro rule and any required reviewers or timers before starting the environment-protected job. Keep the workflow trusted and check out only the recorded SHA. Do not let other uploaded inputs select a different
checkout ref, executable script, or privileged command. The gate cannot prove what arbitrary workflow code executes.GitHub Pro and Team support environment branch restrictions for private repositories, but not this custom App gate. Keep the production environment restricted to
main, and use a separate validation job with read-only permissions and no deployment credentials. Validate that the requested full SHA is an ancestor of the immutable dispatch commit (github.sha). Only then start a deployment job with needs: validate, check out the validated SHA, and obtain deployment credentials in that job.Use that ancestry guard for production applies, not PR plans that intentionally check out an unmerged commit. This workflow pattern prevents an unmerged PR SHA from reaching the deployment job when the trusted workflow and environment branch restriction are intact. It still permits manual dispatches of valid SHAs; it does not provide the Atmos-Pro-only dispatch requirement. A check inside an already privileged deployment job is not equivalent to the external gate.
The most common pattern is to require approvals only for production while allowing staging to deploy automatically:
| Environment | Required Reviewers | Wait Timer | Branch Restriction |
|---|---|---|---|
development | None | None | Any branch |
staging | None | None | main only |
production | Platform team | 5 minutes | main only |
For critical infrastructure components, you can create separate environments with stricter approval requirements:
| Environment | Required Reviewers | Use Case |
|---|---|---|
production | Platform team (1 of 2) | Standard infrastructure |
production-data | DBA team (2 of 3) | Database and data store changes |
production-network | Network team (2 of 2) | VPC, DNS, and networking changes |
We recommend defining GitHub Environments along permissions boundaries — typically by stage (e.g.,
dev,
staging, production). Avoid creating an environment per component or per stack, as this leads to an explosion of
environments in the GitHub UI. Atmos Pro handles fine-grained orchestration; GitHub Environments are best used for
coarse-grained approval gates.Ready to configure deployment approvals?
Set up GitHub environment protection rules to require approval before infrastructure changes are applied.