docs(adr): Commit Status Handling ADR

[elft3r]

what

This Architecture Decision Record tackles the problem of handling the Commit Status in the different VCSs. It describes the context and problem and will further discuss the pros and cons of the chosen solution.

Please add your comments and suggestions to the PR. We will need input from users of all the different supported VCSs.

why

The current implementation of the Commit Status has some bugs and needs to be clarified for some of the VCSs. The first step to fixing the bugs and aligning the different VCS implementations is defining the expected behavior.

references

The following lists represent all the issues I found related to the problem. These already give a good understanding of the problem, what is missing, and suggestions on how to fix it.

The following list shows all the open issues related to the problem:

• gitlab: atlantis/apply job stays pending #2125
• gitlab: Atlantis apply returns Status cannot transition via \"run\" when updating commit check status #2685
• Stuck in-progress apply build in Bitbucket data centre #2971
• Manually planned projects/directories keep atlantis/apply check at 0/0 which allows merging without applying #3852
• Atlantis does not take into account GitHub checks in the Expected - Waiting for status to be reported-state when determining if a pull request is mergeable #4272
• Preventing merging without running atlantis apply on Gitlab #4372

There are also open issues not directly related to the problem at hand. However,
these give a better understanding of what is also needed to solve the problem:

• Rerunning a plan or running an apply should set atlantis/post_workflow_hook to pending #3007
• GitLab pipeline status does not change to success if re-plan is being done #3096
• do not post status checks in github if code changes is not relevent #3340
• Apply fails on Gitlab 16.4.0 with "Pull request must be mergeable before running apply." #3722
• Show progress when running many plans #4023
• Gitlab v4 api 404 errors on commit status update - Wrong URLs vs. API spec? #4313

The last list is features suggested by the community to enhance the capabilities
and allow them a better way of integrating Atlantis into their workflow:

• GitHub Mergability check should support ruleset bypasser status #4116
• If github's automerge is enabled on the PR, then upon approval, check requirements, and automatically atlantis apply #4122
• FEAT: Allow making successful run of terraform apply a statues check on GitHub #4140
• [Feature request] Avoid missing Terraform applies by adding Atlantis user as MR approver #4185
• Approve and Auto-Apply when no changes #4187
• Allow for automerging to happen when a subset of plans are successfully applied #4282