How to implement a change approval workflow

This guide walks you through implementing a change approval workflow in Infrahub. By the end, you'll have a structured process ensuring all infrastructure changes are properly reviewed and approved before being merged into production, enhancing your governance and safety practices.

Enterprise Edition

Some features in this guide require the Enterprise Edition of Infrahub. If you are using the Community Edition, the enforcement mechanisms of the change approval workflow will not be available, though you can still implement a process-based approach.

What you'll build

By the end of this guide, you'll have a complete governance system for infrastructure changes that includes:

• A protected main branch where direct modifications are prevented
• A clear separation between requesters who propose changes and reviewers who approve them
• A mandatory review process requiring explicit approval before changes can be merged
• Automatic approval revocation if changes are modified after being approved

Steps overview

1. Set up roles and permissions for change approvers
2. Enable the change policy configuration in your Infrahub instance
3. Set up permissions for Git repositories
4. Create a proposed change

Prerequisites

Before starting this guide, make sure you have:

• An Infrahub instance with administrator access
• Basic understanding of Infrahub's roles and permissions system
• Familiarity with branching and proposed changes concepts
• Administrative access to the Git repository used by Infrahub
• User management permissions in your Infrahub instance

Creating users and groups

warning

This step can be skipped if you already have appropriate users and groups configured in your Infrahub instance via SSO for instance. Adjust the following steps to match your existing user structure.

We'll create a structure representing a common organizational setup with separate teams having different responsibilities:

1. Navigate to the Admin → Users & Permissions
2. Select the Groups tab and create the following groups:
   • Group name: Support team (responsible for day-to-day support operations)
   • Group name: Network team (responsible for network infrastructure changes)
3. Select the Accounts tab and create the following users:
   • Username: Alice → Assign to group: Network team
   • Username: Charlie → Assign to group: Network team
   • Username: Bob → Assign to group: Support team
   • Username: John → Assign to group: Support team

Validation

You should now see both groups listed in the Groups section and all four users in the Users section, with proper group assignments visible in each user's details.

Step 1: Configure roles and permissions for change approvers

Now, we'll create and assign the necessary roles and permissions to implement our approval workflow:

tip

Adjust these roles and permissions to match your organization's specific needs.

For a complete list of available global and object permissions, see the Permissions documentation.

1. Navigate to the Admin → Users & Permissions
2. Select the Object Permissions tab:
   • Create the following permission
     • Namespace Core
     • Name Proposed Change
     • Action Update
     • Decision Allow in all branches
   • Create the following permission
     • Namespace Core
     • Name Proposed Change
     • Action Create
     • Decision Allow in all branches
   • Create the following permission
     • Namespace Core
     • Name Change Comment
     • Action *
     • Decision Allow in all branches
   • Create the following permission
     • Namespace Core
     • Name Change Thread
     • Action *
     • Decision Allow in all branches
   • Create the following permission
     • Namespace Core
     • Name Thread Comment
     • Action *
     • Decision Allow in all branches
3. Select the Roles tab and create the following roles:
   • Role name: Restricted Access (this role allows edits only to branches other than default)
     • Add group Support team and Network team
     • Add permission: global:edit_default_branch:allow_all
     • Add permission: object:*:*:view:allow_all
     • Add permission: object:*:*:any:allow_other
     • Add permission: object:Core:ChangeComment:any:allow_all
     • Add permission: object:Core:ChangeThread:any:allow_all
     • Add permission: object:Core:ThreadComment:any:allow_all
     • Add permission: object:Core:ProposedChange:create:allow_all
   • Role name: Network Change Reviewer (this role allows full review, approve and merge changes)
     • Add group Network team
     • Add permission: global:review_proposed_change:allow_all
     • Add permission: object:Core:ProposedChange:update:allow_all
     • Add permission: global:merge_proposed_change:allow_all

Validation

With these permissions in place:

• No one can edit directly in the default branch
• All changes must be made in branches and submitted as proposed changes
• Only members of the Network team can review and merge changes
• The Network team is autonomous and can manage the entire approval workflow

Step 2: Enforce change policy Enterprise Edition

Now we'll configure Infrahub's change policy to enforce our approval workflow in order to:

1. Require at least one approval before a proposed change can be merged
2. Automatically revoke approvals if changes are made after approval

important

The configuration process will require a restart of the Infrahub server and depends on your deployment method.

Essentially you will need to set the following environment variables to the desired values:

INFRAHUB_POLICY_REQUIRED_PROPOSED_CHANGE_APPROVALS=<number-of-approvals>
INFRAHUB_POLICY_REVOKE_PROPOSED_CHANGE_APPROVALS=<true|false>

Then restart the Infrahub stack to apply the changes.

Using Docker Compose

1. Set the environment variables:

export INFRAHUB_POLICY_REQUIRED_PROPOSED_CHANGE_APPROVALS=1
export INFRAHUB_POLICY_REVOKE_PROPOSED_CHANGE_APPROVALS=true

2. Rebuild your Docker containers:

docker compose up -d --force-recreate

Validation

You should see the following in Infrahub environment variables:

❯ docker exec infrahub-server-1 env | grep INFRAHUB_POLICY

INFRAHUB_POLICY_REVOKE_PROPOSED_CHANGE_APPROVALS=true
INFRAHUB_POLICY_REQUIRED_PROPOSED_CHANGE_APPROVALS=1

Validation

After setting up those environment variables, proposed changes should now follow the defined approval logic.

Step 3: Secure your Git repositories

To complete our change approval workflow, we need to ensure that only the Infrahub service account can push changes directly to the main branch of your Git repository. This prevents users from bypassing the approval process by making direct commits.

info

• This step only applies if you are using Infrahub's Git integration with a read/write repository.
• Please refer to your Git provider's documentation for specific instructions on configuring branch protection rules.
• Adjust the settings to match your organization's requirements.

Using GitHub

1. Go to your repository's Settings tab
2. Select Branches in the left sidebar
3. Click "Add classic protection rule" or edit existing rule for main
4. Configure the following settings:
   • Branch name pattern: main
   • Check "Require pull request reviews before merging"
     • Tick "Require approvals" and set "Required number of approvals before merging" to 1
     • Tick "Dismiss stale pull request approvals when new commits are pushed"
     • In "Allow specified actors to bypass required pull requests" add your Infrahub service account to the allowed list
5. Click Create or Save changes

Validation

After setting up protection rules, attempt to push directly to the main branch as a regular user - you should receive an error message indicating the branch is protected.

Step 4: Test the approval workflow

Let's verify our workflow by creating a test change and taking it through the entire approval process:

As a requester from Support team

1. Log in as Bob
2. Attempt to edit an object in the main branch
   • You should see that direct edits are not allowed
3. Create a new branch:
   • Name the branch: new-tag
   • Click Create
4. Create a new Tag object:
   • Navigate to Other > Tags
   • Click Add tag
   • Fill in the following attributes:
     • Name: test-tag
     • Description: This is a test tag
   • Click Save
5. Create a proposed change:
   • Click Create proposed change in the branch view
   • Add a title and description for your change
   • Submit the proposed change
   • Note that you cannot merge the proposed change (because approval is required)
   • Note that you cannot approve the proposed change (because you can't approve your own changes)
6. Log out and log in as John
7. Navigate to the Proposed changes section
   • You should see Bob's proposed change listed
   • Note that you cannot approve the proposed change (because you don't have the permission to do so)

As a reviewer from Network team

1. Log out and log in as Alice
2. Navigate to the Proposed changes section
   • You should see Bob's proposed change listed
3. Review the proposed change:
   • Click on the proposed change to open it
   • Review the changes made
   • Add comments if necessary
   • Click Approve to approve the changes
4. Test the approval revocation:
   • Log back in as Bob
   • Make an additional change to the test-tag object
   • Observe that Alice's approval is automatically revoked
5. Complete the workflow:
   • Log back in as Alice
   • Review the updated changes
   • Approve the proposed change again
   • Click Merge to merge the changes into the main branch

Validation

After completing these steps:

• The test-tag should now appear in the main branch
• The change history should show the proper approval flow
• The proposed change should be marked as merged

You now have a fully functional change approval workflow in place!

Advanced use cases

Emergency bypass ("break glass") procedure

In emergency situations, you may need to temporarily bypass the change approval workflow to address critical issues quickly.

Emergency use only

This procedure should only be used in genuine emergency situations, as it bypasses important governance controls and could lead to unintended consequences. All emergency changes should be documented and reviewed after the fact.

To implement an emergency bypass:

1. Use the local "admin" account or a designated emergency account with Super Administrator privileges
2. Log in with this account
3. Make the necessary changes directly or through an expedited proposed change

success

Users with Super Administrator permission can:

• Approve their own proposed changes
• Bypass the minimum approval requirements
• Make direct edits to the main branch

Related resources

• Understanding proposed changes
• Managing users and permissions
• Working with branches
• Configuring Git repositories