{
  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
  "name": "helpbase-workflow",
  "title": "Helpbase Sync Workflow",
  "description": "Drop-in GitHub Actions workflow that runs `helpbase sync` on a schedule and on every push to main. Opens a PR with citation-grounded doc updates whenever a code change would make an MDX doc wrong. Runs in your Actions minutes with your secrets — no SaaS in the path. Requires AI_GATEWAY_API_KEY as a repo secret.",
  "files": [
    {
      "path": "registry/helpbase-workflow/helpbase-sync.yml",
      "content": "name: helpbase sync\n\n# Keep docs in sync with code. Runs weekly and on every push to the base\n# branch. When a code change would make an existing MDX doc wrong,\n# `helpbase sync` proposes citation-grounded edits and this workflow opens\n# a PR you can review.\n#\n# Zero config. Auth happens via GitHub Actions OIDC — the workflow\n# requests a short-lived JWT scoped to helpbase.dev, and the helpbase\n# backend verifies it against GitHub's JWKS. No secrets to paste, no\n# `helpbase login` step, no tokens to rotate. Per-repo quota (500k\n# tokens/day free tier) is tracked by GitHub repository_id so quota\n# follows the repo across renames + org transfers.\n#\n# BYOK override: if you'd rather run on your own provider key (e.g.\n# Anthropic / OpenAI / Vercel AI Gateway), set the corresponding secret\n# under `env:` below — it short-circuits OIDC and calls your provider\n# directly. Everything still runs in *your* Actions minutes.\n\non:\n  schedule:\n    # Monday 09:00 UTC — adjust to your timezone's start-of-week.\n    - cron: \"0 9 * * 1\"\n  push:\n    branches: [main]\n  workflow_dispatch: {}\n\njobs:\n  sync:\n    name: Propose doc updates\n    runs-on: ubuntu-latest\n    permissions:\n      contents: write\n      pull-requests: write\n      # Required to mint the GitHub OIDC token. Tokens are minted per-job\n      # and scoped to the audience below — `https://helpbase.dev` is a\n      # stable identifier hardcoded in the helpbase backend verifier.\n      id-token: write\n    steps:\n      - uses: actions/checkout@v4\n        with:\n          # Fetch enough history for the diff baseline below. github.event.before\n          # points at the prior tip on push events (usually 1 commit back), but\n          # on schedule/manual runs we fall back to HEAD~1 which requires\n          # history beyond the default shallow clone.\n          fetch-depth: 50\n\n      - uses: actions/setup-node@v4\n        with:\n          node-version: \"20\"\n\n      - name: Request GitHub OIDC token\n        id: oidc\n        uses: actions/github-script@v7\n        with:\n          # Matches HELPBASE_OIDC_AUDIENCE in apps/web/lib/oidc-verify.ts.\n          # Do NOT change unless you're also updating the helpbase backend.\n          script: |\n            const token = await core.getIDToken(\"https://helpbase.dev\")\n            core.setSecret(token)\n            core.setOutput(\"token\", token)\n\n      - name: Run helpbase sync\n        env:\n          # GitHub OIDC JWT, zero-config path. The helpbase backend verifies\n          # it against GitHub's JWKS and allocates quota per-repo.\n          HELPBASE_CI_TOKEN: ${{ steps.oidc.outputs.token }}\n          # Optional BYOK overrides. If any of these are set, the CLI\n          # bypasses the helpbase proxy and calls the provider directly.\n          # Leave unset for the zero-config OIDC path.\n          AI_GATEWAY_API_KEY: ${{ secrets.AI_GATEWAY_API_KEY }}\n          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}\n          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}\n        run: |\n          npx -y helpbase sync \\\n            --since ${{ github.event.before || 'HEAD~1' }} \\\n            --apply \\\n            --yes\n\n      - name: Open PR if docs changed\n        env:\n          GH_TOKEN: ${{ github.token }}\n        run: |\n          if [ -z \"$(git status --porcelain)\" ]; then\n            echo \"No doc updates proposed — nothing to PR.\"\n            exit 0\n          fi\n\n          BRANCH=\"helpbase-sync/$(date +%Y%m%d-%H%M%S)\"\n          git config user.name \"helpbase-sync\"\n          git config user.email \"helpbase-sync@users.noreply.github.com\"\n          git checkout -b \"$BRANCH\"\n          git add -A\n          git commit -m \"docs: sync with codebase ($(date +%Y-%m-%d))\"\n          git push origin \"$BRANCH\"\n\n          # `gh pr create` needs \"Allow GitHub Actions to create and\n          # approve pull requests\" enabled under\n          # Settings → Actions → General → Workflow permissions.\n          # It's OFF by default on new repos / orgs. If the PR-create\n          # call 403s on that setting, don't fail the workflow — the\n          # branch is already pushed with the proposed doc update;\n          # the user just needs to open the PR manually (or flip the\n          # setting once).\n          PR_LOG=$(mktemp)\n          if ! gh pr create \\\n                --base \"${GITHUB_REF_NAME}\" \\\n                --head \"$BRANCH\" \\\n                --title \"docs: sync with codebase ($(date +%Y-%m-%d))\" \\\n                --body \"Automated proposal from \\`helpbase sync\\`. Every change cites specific lines of source code — check the diff before merging.\" 2>\"$PR_LOG\"; then\n            if grep -qiE \"not permitted|Resource not accessible\" \"$PR_LOG\"; then\n              echo \"::warning::GitHub Actions is not permitted to open PRs on this repo.\"\n              echo \"::warning::Branch was pushed — open the PR manually:\"\n              echo \"::warning::  https://github.com/${GITHUB_REPOSITORY}/pull/new/${BRANCH}\"\n              echo \"::warning::To auto-open future PRs, enable the 'create and approve pull requests' permission at:\"\n              echo \"::warning::  https://github.com/${GITHUB_REPOSITORY}/settings/actions\"\n              exit 0\n            fi\n            # Unknown failure — re-surface the error, fail the workflow.\n            cat \"$PR_LOG\" >&2\n            exit 1\n          fi\n",
      "type": "registry:file",
      "target": ".github/workflows/helpbase-sync.yml"
    },
    {
      "path": "registry/helpbase-workflow/README.md",
      "content": "# helpbase-workflow\n\nDrop-in GitHub Actions workflow that runs `helpbase sync` on a schedule and\non every push to your main branch. When a code change would make an MDX\ndoc wrong, the workflow opens a PR with the proposed update, grounded in\ncitations into your source.\n\nZero config. No secrets to set. Auth happens via GitHub Actions OIDC.\n\n## Install\n\n```bash\nnpx shadcn add https://helpbase.dev/r/helpbase-workflow.json\n```\n\nThat drops a single file into your repo:\n\n```\n.github/workflows/helpbase-sync.yml\n```\n\nPush the workflow. First scheduled run (or push to `main`) triggers it.\nThat's it.\n\n## One-time setup: let Actions open PRs\n\nGitHub's default setting blocks Actions from opening pull requests. If\nyou don't flip this once, helpbase will still push a branch with the\nproposed docs update on every run, but won't open the PR for you — you'll\nsee a warning in the Action log pointing at the branch URL to open it\nmanually.\n\nTo enable auto-PR, visit:\n\n```\nSettings → Actions → General → Workflow permissions\n  [x] Read and write permissions\n  [x] Allow GitHub Actions to create and approve pull requests\n```\n\nOr via the CLI:\n\n```bash\ngh api --method PUT repos/{owner}/{repo}/actions/permissions/workflow \\\n  -F default_workflow_permissions=write \\\n  -F can_approve_pull_request_reviews=true\n```\n\nFor org-owned repos, this might already be set at the organization level.\n\n## How the auth works\n\nWhen the action runs, GitHub mints a short-lived JSON Web Token that\nidentifies which repository is calling. The workflow passes that token\nto the helpbase backend, which verifies it against GitHub's public keys\nand allocates quota to your repository. Per-repo free tier is 500,000\ntokens/day, reset at UTC midnight. Quota is keyed on the GitHub numeric\n`repository_id`, so it follows the repo across renames and org transfers.\n\nNo token is stored on your side. Each CI run mints a fresh one scoped to\nthis workflow, valid for ~6 minutes, bound to this specific repo.\n\n## BYOK override\n\nIf you'd rather use your own LLM provider account (unlimited, your bill,\nyour choice of model routing), set any of these as a repo secret:\n\n- `AI_GATEWAY_API_KEY` — Vercel AI Gateway\n- `ANTHROPIC_API_KEY`\n- `OPENAI_API_KEY`\n\nWhen any of these is set, the CLI skips the helpbase proxy entirely and\ncalls your provider directly. First env var wins.\n\n## Customize\n\nThe workflow ships with sensible defaults you'll likely want to tweak:\n\n- **Schedule** — default is Monday 09:00 UTC (`cron: \"0 9 * * 1\"`). Edit\n  the `cron` line to match when your team starts the week.\n- **Base branch** — default assumes `main`. If you use `master`, `trunk`,\n  or something else, update `branches: [main]` under `push:`. The diff\n  baseline (`--since`) uses `github.event.before` on push events, so no\n  other branch-name reference needs to change.\n- **Content directory** — zero-config for the three common MDX layouts:\n  `content/` (flat), `content/docs/` (MDX-in-subfolder), and\n  `apps/web/content/` (monorepo). `helpbase sync` walks up from the\n  repo root and picks the first match. If your docs live elsewhere,\n  append `--content <path>` to the `helpbase sync` command, or set\n  `HELPBASE_CONTENT_DIR` in the job's env.\n\n## What the PR looks like\n\nEvery edit in the generated PR carries a `citations` trailer pointing at\nspecific lines of source code that justified the change. Review those\ncitations first — if a citation is missing or wrong, reject the PR; the\nschema makes this rare but not impossible.\n\n## Run locally\n\nTo preview what the workflow would propose, run the same command on your\nmachine:\n\n```bash\n# With your own key:\nAI_GATEWAY_API_KEY=your_key_here \\\n  npx helpbase sync --since origin/main --dry-run\n\n# Or with your logged-in session:\nhelpbase login\nnpx helpbase sync --since origin/main --dry-run\n```\n\nDrop `--dry-run` when you're ready to see the real proposals.\n\n## Upgrading from v0.7 or earlier\n\nEarlier versions of this workflow required you to set `HELPBASE_TOKEN` or\n`AI_GATEWAY_API_KEY` as a repo secret. v0.8+ uses GitHub OIDC by default\nand no secret is needed.\n\nTo upgrade: re-run `npx shadcn@latest add https://helpbase.dev/r/helpbase-workflow.json`.\nIt overwrites the YAML. Then go to `Settings → Secrets and variables →\nActions` and delete `HELPBASE_TOKEN` if you set it before — it's no\nlonger read by the workflow.\n",
      "type": "registry:file",
      "target": ".github/workflows/helpbase-sync.README.md"
    }
  ],
  "type": "registry:item"
}