GitHub Repository Settings
Recommended GitHub repository configuration for infrastructure repositories managed by Atmos Pro.
Atmos Pro builds on the security model and policies of GitHub and GitHub Enterprise. This means the same branch protection rules, required reviews, environment approvals, and audit controls you already use to deploy your applications can be leveraged for infrastructure. Your GitHub repository settings directly affect how Atmos Pro operates — the right configuration ensures clean git history, reliable workflow dispatch, and a smooth deployment experience.
We recommend squash merging for infrastructure repositories. Squash merging collapses all PR commits into a single commit on the base branch, keeping the commit history clean and associating each commit with a single change request (the pull request). This makes it straightforward to audit infrastructure changes, bisect issues, and understand what changed when.
Pull Requests
When merging pull requests, you can allow any combination of merge commits, squashing, or rebasing. At least one option must be enabled. If you have linear history requirement enabled on any protected branch, you must enable squashing or rebasing.
Allow merge commits
Add all commits from the head branch to the base branch with a merge commit.
Allow squash mergingRecommended
Combine all commits from the head branch into a single commit in the base branch.
Default commit message
Presented when merging a pull request with squash.
Default message
Allow rebase merging
Add all commits from the head branch onto the base branch individually.
Control how and when users are prompted to update their branches if there are new changes available in the base branch.
Always suggest updating pull request branchesRecommended
Whenever there are new changes available in the base branch, present an "update branch" option in the pull request.
You can allow setting pull requests to merge automatically once all required reviews and status checks have passed.
Allow auto-merge
Waits for merge requirements to be met and then merges automatically.
After pull requests are merged, you can have head branches deleted automatically.
Automatically delete head branchesRecommended
Deleted branches will still be able to be restored.
Recommended: Enable only squash merging
Disable merge commits
Enable squash merging
Disable rebase merging
Squash merging also ensures reliable affected-stack detection. When Atmos Pro runs
atmos describe affected, it compares the current commit against the base branch — a linear history makes this comparison clean and predictable. With merge commits, branching and merging points can make detection less reliable, especially when multiple PRs land close together. Rebase merging rewrites commit SHAs, which can cause confusion when cross-referencing workflow runs back to specific changes.Infrastructure PRs can conflict with each other in subtle ways. If two PRs modify the same stack configuration, the second one to merge could produce unexpected results. By enabling "Always suggest updating pull request branches", you ensure that the final plan reflects the current state of the base branch.
This is especially important because Atmos Pro dispatches plan workflows on push events — an updated branch triggers a fresh plan that accounts for any recently merged changes.
Infrastructure repositories can accumulate stale branches quickly, especially with automated tooling like Renovate or Dependabot creating update PRs. Enable "Automatically delete head branches" after merge to keep your repository clean. Branches can always be restored if needed.
Branch protection rules on your default branch (usually
main) are critical for infrastructure repositories. They ensure that changes go through proper review and validation before being applied.| Rule | Setting | Why |
|---|---|---|
| Require a pull request before merging | Enabled | All infrastructure changes should be reviewed |
| Require approvals | 1+ approvals | At least one teammate should review changes |
| Require status checks to pass | Enabled | Ensures atmos describe affected and plan workflows succeed |
| Require branches to be up to date | Enabled | Guarantees the plan reflects the current base branch state |
| Require linear history | Enabled | Enforces squash or rebase merging for a clean audit trail |
| Include administrators | Enabled | No one should bypass the process for infrastructure changes |
At minimum, require these status checks before merging:
- Atmos Pro — The overall status check reported by Atmos Pro. This is the single check you should require — it passes only when all plans complete successfully.
- Atmos Affected Stacks — Ensures the affected stacks detection completed successfully
- Terraform Plan — Ensures all plan workflows dispatched by Atmos Pro completed without errors
These checks are automatically reported by the GitHub Actions workflows that Atmos Pro dispatches. By requiring them, you prevent merging (and therefore applying) changes that failed during the plan phase. We recommend requiring Atmos Pro as the primary gate, since it aggregates the results of all downstream checks.
Auto-merge merges a PR as soon as all checks pass and reviews are approved. For application code this is often fine, but for infrastructure changes, we recommend starting with auto-merge disabled to give operators one final moment to review before triggering applies.
That said, auto-merge can work well in combination with Deployment Approvals — the PR merges automatically, but the actual apply still requires manual approval through GitHub Environment protection rules. Consider enabling auto-merge once your team is comfortable with your approval gates.
Atmos Pro uses GitHub webhooks to receive real-time notifications about events in your repository. The webhook is automatically configured when you install the Atmos Pro GitHub App — no manual setup is required.
The app listens for the following events:
| Event | Purpose |
|---|---|
push | Triggers affected stack detection on new commits |
pull_request | Tracks PR lifecycle for plan/apply orchestration |
workflow_run | Monitors dispatched workflow status |
workflow_job | Tracks individual job progress within workflows |
No Manual Webhook Setup
The Atmos Pro GitHub App handles all webhook configuration automatically. You do not need to create or manage webhooks
manually. If you need to verify the webhook is working, check the GitHub App installation in your organization
settings.
The workflows that Atmos Pro dispatches need specific permissions to operate. These are configured in your workflow YAML files, not in repository settings.
permissions:
id-token: write # This is required for requesting the JWT (OIDC) token
contents: read # This is required for actions/checkout
checks: write # This is required for Atmos set gha statuses
statuses: write # This is required to post status checks back to the PR commitFor detailed workflow configuration, see the GitHub Workflows guide.
Ready to configure your repository?
Apply these settings to your infrastructure repository for the best experience with Atmos Pro.