# Chapter 17: GitHub Workflows

## The Problem

You're not working alone. Multiple marketers create segments. Managers need to approve campaigns before launch. Mistakes need catching before they reach production. How do you coordinate?

## The Key Idea

Core concept
GitHub enables team collaboration through pull requests—proposed changes that others can review before they go live.

No one pushes directly to production. Every change is reviewed. Every review is documented.

## The Collaboration Model


```mermaid
flowchart LR
    A[Make Change] --> B[Pull Request]
    B --> C[Review]
    C --> D[Merge]

    A:::you
    B:::propose
    C:::review
    D:::live

    classDef you fill:#e1f5fe
    classDef propose fill:#fff3e0
    classDef review fill:#f3e5f5
    classDef live fill:#e8f5e9
```

This is how software teams have worked for years. It works for marketing configurations too.

## What is GitHub?

GitHub is where your Git repository lives online. It provides:

- **Shared storage:** Everyone accesses the same files
- **Pull requests:** Propose and review changes
- **Discussions:** Comment on specific lines
- **History:** See who changed what, when, and why


## The GitHub CLI

[`gh`](https://cli.github.com/) is GitHub's command-line tool. It lets AI interact with GitHub directly—creating pull requests, checking reviews, merging changes—all from the terminal.


```bash
gh pr create    # Create a pull request
gh pr list      # List open PRs
gh pr merge     # Merge a PR
gh pr checkout  # Check out a PR locally
```

When you ask AI to "create a pull request," it uses `gh` behind the scenes. This is why AI can work with GitHub as easily as it works with local files.

## Creating a Pull Request

You've made changes locally. Now propose them:


```
> "Create a pull request for my segment changes"
```

AI helps you:


```bash
git checkout -b update-high-value-threshold
git add .
git commit -m "Increase high-value threshold to $1000"
git push -u origin update-high-value-threshold
gh pr create --title "Increase high-value threshold to $1000" \
  --body "Updated for Q1 campaign targeting"
```


```
Pull request created:
https://github.com/company/marketing-configs/pull/42
```

Your changes are now proposed, not applied.

## Anatomy of a Pull Request

A pull request shows:


```
┌────────────────────────────────────────────────────────┐
│ PR #42: Increase high-value threshold to $1000         │
├────────────────────────────────────────────────────────┤
│ Author: Sarah                                          │
│ Branch: update-high-value-threshold → main             │
├────────────────────────────────────────────────────────┤
│ Description:                                           │
│ Updated for Q1 campaign targeting. Changing threshold  │
│ from $500 to $1000 reduces audience by ~38%.           │
├────────────────────────────────────────────────────────┤
│ Files changed: 1                                       │
│                                                        │
│ segments/high-value-customers.yaml                     │
│   - value: 500                                         │
│   + value: 1000                                        │
├────────────────────────────────────────────────────────┤
│ Reviews: Pending                                       │
│ Checks: ✓ Validation passed                            │
└────────────────────────────────────────────────────────┘
```

## Reviewing a Pull Request

When someone asks you to review:


```
> "Show me the open pull requests"
```


```
Open pull requests:
#42 - Increase high-value threshold to $1000 (Sarah)
#41 - Add churned customers segment (Mike)
#40 - Update welcome journey timing (Lisa)
```


```
> "Review pull request #42"
```

AI shows you the changes and helps you understand them.

## Adding Review Comments

Comment on specific lines:


```
> "Comment on line 5: Why $1000? Our average order is $150."
```

Start a discussion directly on the code. The author can respond, explain, or adjust.

## Approving or Requesting Changes

After review:

**If it looks good:**


```
> "Approve pull request #42"
```

**If changes are needed:**


```
> "Request changes: Please add a comment explaining the threshold rationale"
```

## Automated Checks

GitHub can run validation automatically:


```yaml
# .github/workflows/validate.yml
name: Validate Configs

on: pull_request

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - run: npm install -g @treasuredata/tdx
      - run: tdx sg validate segments/*.yaml
      - run: tdx journey validate journeys/*.yaml
```

Every pull request is automatically validated. Broken configurations can't be merged.

## Merging

When approved and checks pass:


```
> "Merge pull request #42"
```

The changes become part of main. They're ready to deploy.

## Protected Branches

Prevent direct pushes to main:

- **Require reviews:** At least one approval needed
- **Require checks:** Validation must pass
- **No force push:** History can't be rewritten


This ensures every production change is reviewed.

## The Review Workflow

**For authors:**

1. Create a branch
2. Make changes
3. Open a pull request
4. Address review feedback
5. Wait for approval


**For reviewers:**

1. Read the description
2. Review the changes
3. Comment on concerns
4. Approve or request changes


## Mental Model: Peer Review

Think of pull requests like peer review in publishing:

- You write an article (make changes)
- Submit it for review (open PR)
- Reviewers provide feedback (comments)
- You revise based on feedback (update PR)
- Editor approves (merge)
- Article is published (deployed)


No article goes out unreviewed. No configuration should either.

## Working with AI in Pull Requests

AI can help throughout:

**Creating PRs:**


```
> "Create a PR for my changes with a description of what I modified"
```

**Reviewing PRs:**


```
> "Explain the changes in PR #42"
```

**Responding to feedback:**


```
> "Update the file to address the reviewer's comment about threshold"
```

## PR Best Practices

**Keep PRs small:**

- One segment or journey per PR
- Easier to review, easier to roll back


**Write clear descriptions:**

- What changed and why
- Impact on audience size
- Related campaigns or tickets


**Respond to feedback promptly:**

- Don't let PRs go stale
- Discuss concerns openly


## Team Roles

| Role | Responsibilities |
|  --- | --- |
| **Author** | Create PR, respond to feedback |
| **Reviewer** | Check changes, provide feedback |
| **Approver** | Final sign-off (often a lead/manager) |
| **Merger** | Merge and deploy (may be automated) |


## Pitfalls

**"My PR has been open for days."**

Ping reviewers directly:


```
> "Request review from @manager on PR #42"
```

**"I disagree with the feedback."**

Discuss in the PR comments. Document the decision either way.

**"I need to make more changes."**

Push additional commits to the same branch. The PR updates automatically.

## What You've Learned

- Pull requests propose changes for review
- Team members comment and approve
- Automated checks catch errors
- Protected branches enforce the process
- Every change is documented and traceable
- AI helps throughout the workflow


## Next Step

You've mastered team collaboration. [The Closing](/treasure-code/book/18-closing) wraps up your journey and points you to what's next.

*You've built the complete workflow. Time to wrap up.*