feat: GitHub Action for automatic Linear sync on PR merge

[rubenmarcus]

Summary

Create a GitHub Action that automatically syncs Linear issue status when a ralph-starter PR is merged.

Workflow file

.github/workflows/linear-sync.yml

name: Sync Linear on PR Merge
on:
  pull_request:
    types: [closed]

jobs:
  sync:
    if: github.event.pull_request.merged == true
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npx ralph-starter sync --auto
        env:
          LINEAR_API_KEY: ${{ secrets.LINEAR_API_KEY }}
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

How it works

• Triggered on PR merge (event-driven, no polling)
• Runs on GitHub infrastructure (free for public repos)
• Extracts Linear issue IDs from PR title/branch/body (e.g. ENG-42, auto/ENG-42)
• Updates matched Linear issues to "Done" via API
• Adds comment with PR URL to the Linear issue

Dependencies

• Requires ralph-starter sync command (separate issue)
• Requires LINEAR_API_KEY in GitHub Secrets
• Uses GITHUB_TOKEN for PR context

Acceptance criteria

• Workflow triggers on PR merge
• Extracts Linear issue IDs from PR metadata
• Updates Linear status to "Done"
• Adds comment with PR URL
• No-op when PR has no Linear issue references
• Documented in docs/guides/github-actions.md