GitHub Repository Settings
Recommended GitHub repository configuration for infrastructure repositories managed by Atmos Pro.
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. This page covers the recommended settings and explains why each one matters for infrastructure-as-code repositories.
These settings control how pull requests are merged in your repository. For infrastructure repositories, we recommend a specific configuration that keeps your git history clean and ensures Atmos Pro can reliably detect affected stacks.
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
Why squash merging? When Atmos Pro runs
atmos describe affected, it compares the current commit against the base branch to determine which stacks changed. Squash merging collapses all PR commits into a single commit on the base branch, which makes this comparison clean and predictable.With merge commits, the git history includes branching and merging points that can make affected-stack 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.
Squash merging also produces a linear git history, making it easier to audit infrastructure changes, bisect issues, and understand what changed when.
Why enable this? 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 prompting developers to update their branches before merging, 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.
Why leave this disabled (initially)? 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 an intentional merge 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.
Why enable this? Infrastructure repositories can accumulate stale branches quickly, especially with automated tooling like Renovate or Dependabot creating update PRs. Automatically deleting head branches after merge keeps 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 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.
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.