Skip to main content

Adding Branch Protection to a GitHub Repository

Gruntwork Pipelines is designed to function within a pull request (PR) based workflow. Approving a pull request signals approval to deploy infrastructure, so it's important to configure repository settings and branch protection accurately.

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.

  • Enable Require a pull request before merging to ensure all changes go through a pull request.

  • Enable Require approvals to require at least one approval before merging. Optionally, configure more than one required approval.

  • Enable Require review from code owners for controlled reviews of specific code areas. For more details, see GitHub Documentation.

  • 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.

  • Enable Require branches to be up to date before merging and select the Pipelines workflow as required.

    info

    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.

    Example warning when PR is not up-to-date:

    Recommended Branch Protection SettingsRecommended Branch Protection Settings

Below is an example of the recommended branch protection settings:

Recommended Branch Protection SettingsRecommended Branch Protection Settings

info

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.

info

GitHub Enterprise customers can also configure 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 to enable push rulesets if available.

Securing User Accounts​

Branch protection rules are only effective if you are confident that the users who have access to your repository are legitimate and trusted.

You can improve your security posture by ensuring that:

  1. User accounts have Multi-Factor Authentication (MFA) enabled.
  2. User accounts don't have compromised credentials.
  3. User accounts are granted access to infrastructure-live repositories on a least privilege basis.

Pull Request Workflow​

  1. Developers make infrastructure changes on a branch and create a pull request (PR) against the default branch.
  2. On pull request creation, Gruntwork Pipelines runs plan for any changes and posts the results as a comment.
  3. Gruntwork Pipelines re-runs plan on every push to the branch and updates the results in a comment.
  4. Gather approvals. If Code Owners is enabled, all relevant code owners must approve the changes.
  5. Once approved, merge the pull request into the default branch.
  6. Gruntwork Pipelines runs apply for the changes from the pull request.
    • On success, the pull request is updated to indicate the successful apply.
    • On failure, the pull request is updated to indicate the failure of the apply. If the failure cannot be resolved by retrying, a new pull request must be created to address the issues.