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

[github-actions]

This issue has been automatically marked as stale because it has not had recent activity.
It will be closed in 14 days if no further activity occurs.
If this issue is still relevant, please comment or remove the stale label.