Set Up GitOps Workflow

Implement a PR-based infrastructure workflow where all changes go through code review, automatic plans appear as comments, and merging triggers deployment.

Scenario

Your team wants to:

Require code review for all infrastructure changes
See Terraform plans before approving PRs
Automatically deploy when PRs are merged
Have a complete audit trail in Git history

This guide sets up a complete GitOps workflow with GitHub integration.

Prerequisites

✓ops0 IaC project with code you want to manage

✓GitHub repository (can be new or existing)

✓GitHub organization admin access (for installing the ops0 app)

Step 1: Install ops0 GitHub App

1Go to Settings > Integrations

2Click Add Integration > GitHub

3Click Install GitHub App

4Select your GitHub organization

5Choose which repositories ops0 can access (specific repos recommended)

6Click Install & Authorize

Permissions Requested

Permission	Purpose
Read code	Clone repositories
Write pull requests	Post plan comments
Write commit status	Update check status
Read/write webhooks	Receive PR events

Step 2: Connect Your IaC Project to a Repository

1Open your IaC project in ops0

2Go to Project Settings > GitHub Sync

3Click Connect Repository

4Select the repository from the dropdown

5Configure branch settings:

Branch Configuration

Setting	Recommended Value	Purpose
Default Branch	`main`	Where production code lives
Working Directory	`/` or `/terraform`	Path to Terraform files in repo
Auto-sync	Enabled	Pull changes from GitHub automatically

Step 3: Initial Sync

If your ops0 project already has code, push it to GitHub:

1Click Push to GitHub

2Enter a commit message: "Initial Terraform configuration"

3Select target branch (main)

4Click Push

If GitHub already has code, click Pull from GitHub instead.

Step 4: Configure PR Automation

Set up what happens when PRs are created:

1In Project Settings > GitHub Sync, scroll to PR Automation

2Enable the automation options:

Automation Options

Auto-plan on PR

Run terraform plan automatically when a PR is opened or updated.

Post plan as comment

Add the plan output as a comment on the PR for easy review.

Update commit status

Set GitHub check status based on plan/policy results.

Auto-apply on merge

Automatically run terraform apply when PR is merged. Enable with caution.

Step 5: Set Up Branch Protection (GitHub)

To enforce the GitOps workflow, configure GitHub branch protection:

1Go to your GitHub repository > Settings > Branches

2Click Add rule for the main branch

3Enable these protections:

Recommended Settings

Setting	Value
Require pull request before merging	Yes
Required approvals	1 (or more for production)
Require status checks	Yes
Required checks	`ops0/terraform-plan`, `ops0/policy-check`
Require branches to be up to date	Yes

Step 6: Test the Workflow

Let's verify everything works:

Create a Test PR

1Create a new branch in ops0 or GitHub

2Make a small change (e.g., add a tag to a resource)

3Open a Pull Request against main

What You Should See

Within 30-60 seconds:

GitHub Check Status

✓ ops0/terraform-plan - Plan succeeded: 0 to add, 1 to change, 0 to destroy
✓ ops0/policy-check - All policies passed

PR Comment

### Terraform Plan

Changes: 0 to add, 1 to change, 0 to destroy
Cost Impact: +$0.00/month

~ aws_instance.web_server
    ~ tags.Environment: "dev" -> "development"

View full plan in ops0

Step 7: Configure Auto-Apply (Optional)

If you want changes to deploy automatically when PRs are merged:

1Enable Auto-apply on merge in Project Settings

2Configure which branches trigger auto-apply (e.g., only main)

3Optionally require approval before apply (via ops0 Workflows)

With Approval Workflow

For production environments, add a human checkpoint:

PR Merged
    │
    ▼
Auto-plan runs
    │
    ▼
Approval request sent (Slack/Email)
    │
    ▼
Approver clicks "Approve" in ops0
    │
    ▼
Terraform apply executes
    │
    ▼
Result posted to PR/Slack

See Create Approval Workflows for setup details.

Daily Workflow

Once set up, here's how your team works:

1Developer creates branch - In ops0 or locally with Git

2Developer makes changes - Edit Terraform in ops0 editor or IDE

3Developer opens PR - ops0 automatically runs plan

4Team reviews - Check plan in PR comment, review code

5PR merged - Auto-apply runs (or manual apply in ops0)

6Changes deployed - Result posted to PR and Slack

Troubleshooting

Plan Not Running on PR

Check	Solution
GitHub App installed?	Verify in Settings > Integrations
Correct repository?	Confirm repo is connected in Project Settings
Webhooks working?	Check GitHub repo > Settings > Webhooks for delivery status
Working directory correct?	Ensure path matches where Terraform files are

Status Checks Not Appearing

Ensure "Update commit status" is enabled
Check that branch protection is configured correctly
Verify the ops0 check names match exactly

Merge Conflicts

If ops0 and GitHub have diverged:

Pull latest from GitHub in ops0
Resolve conflicts in the editor
Push merged result back

Next Steps

Add Approval Workflows

Require human approval before production deploys

Enforce Security Policies

Block non-compliant PRs automatically