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.
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
- Set up roles and permissions for change approvers
- Enable the change policy configuration in your Infrahub instance
- Set up permissions for Git repositories
- 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
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:
- Navigate to the Admin → Users & Permissions
- 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)
- Group name:
- 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
- Username:
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:
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.
- Navigate to the Admin → Users & Permissions
- Select the Object Permissions tab:
- Create the following permission
- Namespace
Core
- Name
Proposed Change
- Action
Update
- Decision
Allow in all branches
- Namespace
- Create the following permission
- Namespace
Core
- Name
Change Comment
- Action
*
- Decision
Allow in all branches
- Namespace
- Create the following permission
- Namespace
Core
- Name
Change Thread
- Action
*
- Decision
Allow in all branches
- Namespace
- Create the following permission
- Namespace
Core
- Name
Thread Comment
- Action
*
- Decision
Allow in all branches
- Namespace
- Create the following permission
- 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
andNetwork 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 group
- 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
- Add group
- Role name:
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:
- Require at least one approval before a proposed change can be merged
- Automatically revoke approvals if changes are made after approval
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
- Set the environment variables:
export INFRAHUB_POLICY_REQUIRED_PROPOSED_CHANGE_APPROVALS=1
export INFRAHUB_POLICY_REVOKE_PROPOSED_CHANGE_APPROVALS=true
- Rebuild your Docker containers:
docker compose up -d --force-recreate
You should see the following in Infrahub environment variables:
INFRAHUB_POLICY_REVOKE_PROPOSED_CHANGE_APPROVALS=true
INFRAHUB_POLICY_REQUIRED_PROPOSED_CHANGE_APPROVALS=1
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.
- 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
- Go to your repository's Settings tab
- Select Branches in the left sidebar
- Click "Add classic protection rule" or edit existing rule for main
- 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
- Tick "Require approvals" and set "Required number of approvals before merging" to
- Branch name pattern:
- Click Create or Save changes
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
- Log in as
Bob
- Attempt to edit an object in the main branch
- You should see that direct edits are not allowed
- Create a new branch:
- Name the branch:
new-tag
- Click Create
- Name the branch:
- 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
- Name:
- Click Save
- 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)
- Log out and log in as
John
- 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
- Log out and log in as
Alice
- Navigate to the Proposed changes section
- You should see Bob's proposed change listed
- 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
- 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
- Log back in as
- 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
- Log back in as
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.
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:
- Use the local "admin" account or a designated emergency account with
Super Administrator
privileges - Log in with this account
- Make the necessary changes directly or through an expedited proposed change
Users with Super Administrator
permission can:
- Approve their own proposed changes
- Bypass the minimum approval requirements
- Make direct edits to the main branch