In April 2024, the Core Atlantis Team launched an anonymous survey to better understand our community's needs and help prioritize our roadmap.
If you're an Atlantis user, please take 5 minutes to fill it out: Survey Link
In April 2024, the Core Atlantis Team launched an anonymous survey to better understand our community's needs and help prioritize our roadmap.
If you're an Atlantis user, please take 5 minutes to fill it out: Survey Link
Atlantis requires certain conditions be satisfied before atlantis apply
and atlantis import
commands can be run:
If the requirement is not met, users will see an error if they try to run atlantis apply
:
The approved
requirement will prevent applies unless the pull request is approved by at least one person other than the author.
The approved
requirement by:
Creating a repos.yaml
file with the apply_requirements
key:
repos:
- id: /.*/
apply_requirements: [approved]
Or by allowing an atlantis.yaml
file to specify the apply_requirements
key in the repos.yaml
config:
repos.yaml
repos:
- id: /.*/
allowed_overrides: [apply_requirements]
atlantis.yaml
version: 3
projects:
- dir: .
apply_requirements: [approved]
Each VCS provider has different rules around who can approve:
Tip
To require certain people to approve the pull request, look at the mergeable requirement.
The mergeable
requirement will prevent applies unless a pull request is able to be merged.
Set the mergeable
requirement by:
Creating a repos.yaml
file with the apply_requirements
key:
repos:
- id: /.*/
apply_requirements: [mergeable]
Or by allowing an atlantis.yaml
file to specify plan_requirements
, apply_requirements
and import_requirements
keys in the repos.yaml
config:
repos.yaml
repos:
- id: /.*/
allowed_overrides: [plan_requirements, apply_requirements, import_requirements]
atlantis.yaml
version: 3
projects:
- dir: .
plan_requirements: [mergeable]
apply_requirements: [mergeable]
import_requirements: [mergeable]
Each VCS provider has a different concept of "mergeability":
WARNING
Some VCS providers have a feature for branch protection to control "mergeability". To use it, limit the base branch so to not bypass the branch protection. See also the branch
keyword in Server Side Repo Config for more details.
In GitHub, if you're not using Protected Branches then all pull requests are mergeable unless there is a conflict.
If you set up Protected Branches then you can enforce:
CODEOWNERS
to have reviewed and approved the pull requestmain
See GitHub: About protected branches for more details.
WARNING
If you have the Restrict who can push to this branch requirement, then the Atlantis user needs to be part of that list in order for it to consider a pull request mergeable.
WARNING
If you set atlantis/apply
to the mergeable requirement, use the --gh-allow-mergeable-bypass-apply
flag or set the ATLANTIS_GH_ALLOW_MERGEABLE_BYPASS_APPLY=true
environment variable. This flag and environment variable allow the mergeable check before executing atlantis apply
to skip checking the status of atlantis/apply
.
For GitLab, a merge request will be merged if there are no conflicts, no unresolved discussions if it is a project requirement and if all necessary approvers have approved the pull request.
For pipelines, if the project requires that pipelines must succeed, all builds except the apply command status will be checked.
For Jobs with allow_failure setting set to true, will be ignored. If the pipeline has been skipped and the project allows merging, it will be marked as mergeable.
For Bitbucket, we just check if there is a conflict that is preventing a merge. We don't check anything else because Bitbucket's API doesn't support it.
If you need a specific check, please open an issue.
In Azure DevOps, all pull requests are mergeable unless there is a conflict. You can set a pull request to "Complete" right away, or set "Auto-Complete", which will merge after all branch policies are met. See Review code with pull requests.
Branch policies can:
WARNING
At this time, the Azure DevOps client only supports merging using the default 'no fast-forward' strategy. Make sure your branch policies permit this type of merge.
Prevent applies if there are any changes on the base branch since the most recent plan. Applies to merge
checkout strategy only which you need to set via --checkout-strategy
flag.
You can set the undiverged
requirement by:
Creating a repos.yaml
file with plan_requirements
, apply_requirements
and import_requirements
keys:
repos:
- id: /.*/
plan_requirements: [undiverged]
apply_requirements: [undiverged]
import_requirements: [undiverged]
Or by allowing an atlantis.yaml
file to specify the plan_requirements
, apply_requirements
and import_requirements
keys in your repos.yaml
config:
repos.yaml
repos:
- id: /.*/
allowed_overrides: [plan_requirements, apply_requirements, import_requirements]
atlantis.yaml
version: 3
projects:
- dir: .
plan_requirements: [undiverged]
apply_requirements: [undiverged]
import_requirements: [undiverged]
The merge
checkout strategy creates a temporary merge commit and runs the plan
on the Atlantis local version of the PR source and destination branch. The local destination branch can become out of date since changes to the destination branch are not fetched if there are no changes to the source branch. undiverged
enforces that Atlantis local version of main is up to date with remote so that the state of the source during the apply
is identical to that if you were to merge the PR at that time.
As mentioned above, you can set command requirements via flags, in repos.yaml
, or in atlantis.yaml
if repos.yaml
allows the override.
Flags override any repos.yaml
or atlantis.yaml
settings so they are equivalent to always having that apply requirement set.
If you only want some projects/repos to have apply requirements, then you must
Specifying which repos have which requirements via the repos.yaml
file.
repos:
- id: /.*/
plan_requirements: [approved]
apply_requirements: [approved]
import_requirements: [approved]
# Regex that defaults all repos to requiring approval
- id: /github.com/runatlantis/.*/
# Regex to match any repo under the atlantis namespace, and not require approval
# except for repos that might match later in the chain
plan_requirements: []
apply_requirements: []
import_requirements: []
- id: github.com/runatlantis/atlantis
plan_requirements: [approved]
apply_requirements: [approved]
import_requirements: [approved]
# Exact string match of the github.com/runatlantis/atlantis repo
# that sets apply_requirements to approved
Specify which projects have which requirements via an atlantis.yaml
file, and allowing plan_requirements
, apply_requirements
and import_requirements
to be set in atlantis.yaml
by the server side repos.yaml
config.
For example if I have two directories, staging
and production
, I might use:
repos.yaml:
repos:
- id: /.*/
allowed_overrides: [plan_requirements, apply_requirements, import_requirements]
# Allow any repo to specify apply_requirements in atlantis.yaml
atlantis.yaml:
version: 3
projects:
- dir: staging
# By default, plan_requirements, apply_requirements and import_requirements are empty so this
# isn't strictly necessary.
plan_requirements: []
apply_requirements: []
import_requirements: []
- dir: production
# This requirement will only apply to the
# production directory.
plan_requirements: [mergeable]
apply_requirements: [mergeable]
import_requirements: [mergeable]
You can set any or all of approved
, mergeable
, and undiverged
requirements.
Once the apply requirement is satisfied, anyone that can comment on the pull request can run the actual atlantis apply
command.