# Set Up GitOps Workflow

Source: https://docs.ops0.com/docs/how-to/setup-gitops

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

1. Go to **Settings** > **Integrations**

2. Click **Add Integration** > **GitHub**

3. Click **Install GitHub App**

4. Select your GitHub organization

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

6. Click **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

1. Open your IaC project in ops0

2. Go to **Project Settings** > **GitHub Sync**

3. Click **Connect Repository**

4. Select the repository from the dropdown

5. Configure 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:

1. Click **Push to GitHub**

2. Enter a commit message: "Initial Terraform configuration"

3. Select target branch (`main`)

4. Click **Push**

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

---

## Step 4: Configure PR Automation

Set up what happens when PRs are created:

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

2. Enable 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:

1. Go to your GitHub repository > **Settings** > **Branches**

2. Click **Add rule** for the `main` branch

3. Enable 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

1. Create a new branch in ops0 or GitHub

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

3. Open 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:

1. Enable **Auto-apply on merge** in Project Settings

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

3. Optionally 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](https://docs.ops0.com/docs/how-to/approval-workflows) for setup details.

---

## Daily Workflow

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

1. **Developer creates branch** - In ops0 or locally with Git

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

3. **Developer opens PR** - ops0 automatically runs plan

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

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

6. **Changes 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:
1. Pull latest from GitHub in ops0
2. Resolve conflicts in the editor
3. Push merged result back

---

## Next Steps

[Add Approval Workflows Require human approval before production deploys](https://docs.ops0.com/docs/how-to/approval-workflows)
[Enforce Security Policies Block non-compliant PRs automatically](https://docs.ops0.com/docs/how-to/enforce-security-policies)