|
1 | 1 | # Branch Protection |
2 | 2 |
|
3 | | -Gruntwork Pipelines is designed to be used with a PR based workflow. |
4 | | -This means an approval on a PR is an approval to deploy infrastructure, making the configuration of repository settings and branch protection especially important. |
| 3 | +Gruntwork Pipelines is designed to function within a PR-based workflow. Approving a pull request (PR) signals approval to deploy infrastructure, so it's important to configure repository settings and branch protection accurately. |
5 | 4 |
|
6 | | -## Recommended Settings |
| 5 | +## Recommended settings |
7 | 6 |
|
8 | | -By default, Gruntwork pipelines runs a plan on every push to a PR and an apply on every push to `main`. |
9 | | -Branch protection should be enabled on `main` to prevent changes from being applied without approval. |
| 7 | +By default, Gruntwork Pipelines runs a `plan` on every push to a PR and an `apply` on every push to `main`. To ensure that infrastructure changes are reviewed and approved before deployment, branch protection should be enabled on `main` to prevent unauthorized changes. |
| 8 | + |
| 9 | +- Enable **Require a pull request before merging** to ensure all changes go through a pull request. |
| 10 | +- Enable **Require approvals** to require at least one approval before merging. Optionally, configure more than one required approval. |
| 11 | +- Enable **Require review from code owners** for controlled reviews of specific code areas. For more details, see [GitHub Documentation](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners). |
| 12 | +- Enable **Require status checks to pass before merging** to ensure the `apply` does not run if the `plan` fails, or if organizational validation rules fail. |
| 13 | +- Enable **Require branches to be up to date before merging** and select the `Pipelines` workflow as required. |
10 | 14 |
|
11 | | -- **Require a pull request before merging** should be enabled. |
12 | | -- **Require approvals** should be enabled. Optionally, more than one approval could be required. |
13 | | -- **Require review from Code Owners** should be enabled if you need control over which users are required to review specific code areas. See the [GitHub Documentation](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners) for more information. |
14 | | -- **Require status checks to pass before merging** should be enabled. |
15 | | - :::info |
16 | | - This prevents `apply` from running when `plan` fails and ensures any validation rules your organization has put in place have been run. |
17 | | - ::: |
18 | | -- **Require branches to be up to date before merging** should be enabled with the `Pipelines` workflow selected as required. |
19 | 15 | :::info |
20 | | - This option prevents `apply` from running with an inaccurate `plan`, but has a tradeoff of increased GitHub Actions minute usage. |
21 | | - When the PR is not up to date you will see the following message: |
| 16 | + |
| 17 | + This prevents running an inaccurate `apply` by ensuring the PR is up-to-date. However, it increases GitHub Actions minute usage. If disabled, another PR merged into `main` after the `plan` could lead to an inaccurate `apply`. Evaluate whether this tradeoff aligns with your organization's risk tolerance. |
| 18 | + |
| 19 | + Example warning when PR is not up-to-date: |
| 20 | + |
22 | 21 |  |
23 | | - With this option disabled, another PR could be merged into `main` after this PR has run `plan`. No new plan would be run |
24 | | - in that scenario, so the `apply` has a higher likelihood of failure. If this risk is acceptable to your organization you may |
25 | | - choose to ignore this recommendation. |
| 22 | + |
26 | 23 | ::: |
27 | 24 |
|
28 | | -The following is an example of the recommended settings for branch protection: |
| 25 | +Below is an example of the recommended branch protection settings: |
| 26 | + |
29 | 27 |  |
30 | 28 |
|
31 | 29 | :::info |
32 | | - You may wish to enable **Do not allow bypassing the above settings** to prevent admins from bypassing the branch |
33 | | - protection rules. This will limit your options for applying emergency fixes, but is more secure. |
| 30 | + Consider enabling **Do not allow bypassing the above settings** to prevent admins from bypassing branch protection rules. While this improves security, it may limit options for emergency fixes. |
34 | 31 | ::: |
35 | 32 |
|
36 | 33 | :::info |
37 | | - As of writing, GitHub has also released new functionality that is broadly only available to GitHub Enterprise customers. |
38 | | - This beta functionality allows for configuring [push rulesets](https://docs.github.com/en/enterprise-cloud@latest/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/about-rulesets#push-rulesets). To configure it, follow the documentation [here](https://docs.github.com/en/enterprise-cloud@latest/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/creating-rulesets-for-a-repository#creating-a-push-ruleset). |
39 | | - Enabling this feature is recommended if it is available for you, as it allows you to prevent edits to `.github/workflows` files, ensuring that all infrastructure changes are reviewed, approved and propagated through Pipelines. |
40 | | - |
41 | | -## PR Workflow |
42 | | - |
43 | | -1. Developers make infrastructure changes on a branch and create a PR against `main` |
44 | | -1. On PR creation, Gruntwork Pipelines runs `plan` on any changes and posts the results as a comment |
45 | | -1. Gruntwork Pipelines re-runs `plan` on every push to the branch and posts results as a comment |
46 | | -1. Approvals are gathered. If codeowners is enabled, the owner of each changed folder/file must approve the PR before it can be merged |
47 | | -1. Once approved, the PR is merged into `main` |
48 | | -1. Gruntwork Pipelines runs `apply` on any changes from the PR |
49 | | - - On Success, the PR is updated to communicate the success of the apply |
50 | | - - On Failure, the PR is updated to communicate the failure of the apply. If the apply cannot be fixed by retrying, a new PR must be created to resolve any failures. |
| 34 | + GitHub Enterprise customers can also configure [push rulesets](https://docs.github.com/en/enterprise-cloud@latest/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/about-rulesets#push-rulesets). This feature allows restricting edits to `.github/workflows` files, ensuring infrastructure changes are properly reviewed and approved through Pipelines. Follow the documentation [here](https://docs.github.com/en/enterprise-cloud@latest/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/creating-rulesets-for-a-repository#creating-a-push-ruleset) to enable push rulesets if available. |
| 35 | +::: |
| 36 | + |
| 37 | + |
| 38 | +## PR workflow |
| 39 | + |
| 40 | +1. Developers make infrastructure changes on a branch and create a PR against `main`. |
| 41 | +2. On PR creation, Gruntwork Pipelines runs `plan` for any changes and posts the results as a comment. |
| 42 | +3. Gruntwork Pipelines re-runs `plan` on every push to the branch and updates the results in a comment. |
| 43 | +4. Gather approvals. If Code Owners is enabled, all relevant code owners must approve the PR. |
| 44 | +5. Once approved, merge the PR into `main`. |
| 45 | +6. Gruntwork Pipelines runs `apply` for the changes from the PR. |
| 46 | + - On success, the PR is updated to indicate the successful `apply`. |
| 47 | + - On failure, the PR is updated to indicate the failure of the `apply`. If the failure cannot be resolved by retrying, a new PR must be created to address the issues. |
0 commit comments