04. CI/CD INTEGRATION

🤔 When do you need CI/CD?

You need the GitHub Actions workflow only if all of these are true:

• Your team merges Pull Requests through the GitHub web UI (not via local git merge)
• You want CLAUDE.md (or your context file) committed back to the repo so teammates see the updated context without pulling first
• Not all teammates have Briefed installed locally

If you merge PRs locally (git pull → git merge), the post-merge hook already handles everything. No CI needed.

🐙 GitHub Actions Blueprint

Create .github/workflows/briefed.yml in your project:

name: Briefed Context Update

on:
  push:
    branches:
      - main  # Adjust to your default branch

permissions:
  contents: write

jobs:
  briefed-context:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
        with:
          fetch-depth: 2  # Need parent commit to diff against

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 18

      - name: Check API Keys availability
        id: check-keys
        shell: bash
        run: |
          if [ -n "$GEMINI_API" ] || [ -n "$BRIEFED_API" ] || [ -n "$ANTHROPIC_API" ]; then
            echo "has_keys=true" >> "$GITHUB_OUTPUT"
          else
            echo "has_keys=false" >> "$GITHUB_OUTPUT"
          fi
        env:
          GEMINI_API: ${{ secrets.GEMINI_API_KEY }}
          BRIEFED_API: ${{ secrets.BRIEFED_API_KEY }}
          ANTHROPIC_API: ${{ secrets.ANTHROPIC_API_KEY }}

      - name: Install Briefed
        if: steps.check-keys.outputs.has_keys == 'true'
        run: npm install -g briefed-cli

      - name: Set ORIG_HEAD manually
        if: steps.check-keys.outputs.has_keys == 'true'
        run: git update-ref ORIG_HEAD $(git rev-parse HEAD~1)

      - name: Run briefed
        if: steps.check-keys.outputs.has_keys == 'true'
        run: briefed run
        env:
          BRIEFED_API_KEY: ${{ secrets.BRIEFED_API_KEY }}
          GEMINI_API_KEY: ${{ secrets.GEMINI_API_KEY }}
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}

      - name: Commit context changes
        if: steps.check-keys.outputs.has_keys == 'true'
        run: |
          # Detects whichever context file briefed updated (CLAUDE.md, AGENTS.md, etc.)
          CHANGED=$(git diff --name-only | grep -E '^(CLAUDE\.md|AGENTS\.md|\.github/copilot-instructions\.md)$' | head -1)
          if [ -n "$CHANGED" ]; then
            git config --local user.name "github-actions[bot]"
            git config --local user.email "github-actions[bot]@users.noreply.github.com"
            git add "$CHANGED"
            git commit -m "Update AI context [skip ci]"
            git push
          fi

⚙️ What each step does

1. fetch-depth: 2

GitHub's default checkout only fetches the latest commit (depth 1). Briefed needs to compare the current commit against its parent, so fetch-depth: 2 is required.

2. npm install -g briefed-cli

Installs the published CLI from npm. No source checkout or TypeScript compilation needed — just the released package.

3. git update-ref ORIG_HEAD $(git rev-parse HEAD~1)

During local merges, Git sets ORIG_HEAD automatically. CI runners don't have this reference, so we set it manually to HEAD~1 (the previous commit) before running Briefed.

4. [skip ci] in the commit message

When the workflow commits the updated context file back to the repo, it would normally trigger another workflow run — creating an infinite loop. The [skip ci] tag instructs GitHub Actions to skip that trigger.