{"id":47770570,"url":"https://github.com/popsa-hq/auto-docs","last_synced_at":"2026-04-03T09:03:37.627Z","repository":{"id":337277293,"uuid":"1152887786","full_name":"popsa-hq/auto-docs","owner":"popsa-hq","description":"Documentation auto-update pipeline powered by Claude Code and GitHub Actions","archived":false,"fork":false,"pushed_at":"2026-02-08T17:39:24.000Z","size":10,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-08T23:33:44.602Z","etag":null,"topics":["automation","claude-code","documentation","github-actions"],"latest_commit_sha":null,"homepage":null,"language":null,"has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/popsa-hq.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-08T15:38:19.000Z","updated_at":"2026-02-08T17:39:27.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/popsa-hq/auto-docs","commit_stats":null,"previous_names":["popsa-hq/auto-docs"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/popsa-hq/auto-docs","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/popsa-hq%2Fauto-docs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/popsa-hq%2Fauto-docs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/popsa-hq%2Fauto-docs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/popsa-hq%2Fauto-docs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/popsa-hq","download_url":"https://codeload.github.com/popsa-hq/auto-docs/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/popsa-hq%2Fauto-docs/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31344470,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-03T08:03:20.796Z","status":"ssl_error","status_checked_at":"2026-04-03T08:00:37.834Z","response_time":107,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["automation","claude-code","documentation","github-actions"],"created_at":"2026-04-03T09:03:35.639Z","updated_at":"2026-04-03T09:03:37.611Z","avatar_url":"https://github.com/popsa-hq.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"# auto-docs\n\nA documentation auto-update pipeline powered by [Claude Code](https://claude.com/product/claude-code) and [GitHub Actions](https://github.com/features/actions). When code merges to your repositories, the pipeline detects which documentation files are affected, runs an AI agent to update them, and opens a pull request for human review.\n\n## How it works\n\n```text\nSource Repo (merge to main)\n  --\u003e docs-notify.yml\n       --\u003e repository_dispatch to your-org/your-docs-repo\n            --\u003e auto-docs-update.yml\n                 |-- checkout docs + source repo\n                 |-- match changed paths to affected doc files\n                 |-- run Claude Code to regenerate docs\n                 --\u003e open PR with \"auto-docs\" label\n```\n\n1. An engineer merges code to a source repository.\n2. A lightweight **sender** workflow (`docs-notify.yml`) fires, collects the changed file paths and commit reference, and dispatches a [`repository_dispatch`](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#repository_dispatch) event to your central documentation repository.\n3. The **receiver** workflow (`auto-docs-update.yml`) picks up the event and consults `docs-config.yml` to determine which documentation files could be affected by the change, using glob-based `watch_paths`.\n4. For each affected doc, Claude Code reads the existing documentation, explores the source repository at the exact triggering commit, compares the two, and proposes targeted edits.\n5. If changes are needed, a PR is opened for human review. If nothing meaningful changed, the pipeline closes cleanly (`NO_CHANGES_NEEDED`).\n\n## Setup\n\n### Prerequisites\n\n- An [Anthropic API key](https://console.anthropic.com/) for Claude Code\n- A [GitHub Personal Access Token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens) (PAT) with `repo` scope, used to dispatch events and check out private source repos\n\n### Docs repository\n\n1. Copy `auto-docs-update.yml` into your docs repo at `.github/workflows/auto-docs-update.yml`.\n2. Copy `docs-config.example.yml` to `.github/docs-config.yml` and customise it for your repositories (see [Configuration](#configuration) below).\n3. Copy `auto-docs-prompt.example.md` to `.github/auto-docs-prompt.md` and adjust the rules to match your team's conventions.\n4. Add the following secrets to your docs repo:\n   - `CLAUDE_API_KEY` — your Anthropic API key\n   - `DOCS_DISPATCH_TOKEN` — the GitHub PAT\n5. Create an `auto-docs` label in your docs repo (used to tag auto-generated PRs).\n\n### Source repositories\n\nFor each repo you want to participate:\n\n1. Copy `docs-notify.yml` into the repo at `.github/workflows/docs-notify.yml`.\n2. Update the `branches` trigger if your default branch isn't `main`.\n3. Update the `repository` field in the dispatch step to point at your docs repo.\n4. Add the `DOCS_DISPATCH_TOKEN` secret (the same GitHub PAT).\n5. Add an entry in your docs repo's `docs-config.yml` for this source repo.\n\n## Configuration\n\nThe `docs-config.yml` file maps source repositories to the documentation files they affect:\n\n```yaml\nrepositories:\n  org/backend:\n    branch: main                    # Branch that triggers updates\n    checkout_path: source/backend   # Where to clone the source repo\n    docs:\n      - file: standards/go.md      # Doc file in the docs repo\n        scope: \"Go coding standards, conventions, and tooling\"\n        watch_paths:                # Globs matched against changed files\n          - \"**/*.go\"\n          - \"go.mod\"\n          - \".golangci.yml\"\n```\n\n- **`branch`** — the source repo branch that triggers docs updates.\n- **`checkout_path`** — a temporary directory for cloning the source repo during the workflow run.\n- **`docs[].file`** — path to the documentation file in your docs repo.\n- **`docs[].scope`** — a natural-language description of what this doc covers, passed to Claude as context.\n- **`docs[].watch_paths`** — glob patterns matched against the changed file paths. Only docs whose watch_paths intersect with actual changes are regenerated.\n\nWildcard entries (e.g., `org/*`) act as a fallback for repositories without an explicit entry.\n\n### Prompt template\n\nThe `auto-docs-prompt.md` template supports these variables, substituted at runtime:\n\n| Variable | Description |\n|---|---|\n| `$DOC_FILE` | Path to the documentation file being updated |\n| `$SOURCE_PATH` | Path to the checked-out source repository |\n| `$REPOSITORY` | Full `org/repo` name of the source repository |\n| `$SCOPE` | The scope string from `docs-config.yml` |\n| `$CHANGED_PATHS` | Comma-separated list of files changed in the triggering commit |\n| `$SHA` / `$SHA_SHORT` | Full and abbreviated commit SHA |\n| `$BRANCH` | Source branch name |\n| `$COMPONENT` | Derived from the doc filename (e.g., `standards/go.md` yields `go`) |\n\n## Design decisions\n\n- **Event-driven, not scheduled.** Source repos push events when changes happen. No polling, no cron. Any new repository can participate by adding the sender workflow and a config entry.\n- **Concurrency queuing.** Only one documentation update per source repository runs at a time. If two PRs merge in quick succession, the second update queues rather than being discarded.\n- **`NO_CHANGES_NEEDED` exit.** Not every code change affects documented conventions. Claude can determine that no docs update is required, and the pipeline closes cleanly without opening a PR.\n- **Human review required.** Auto-merge is deliberately not included. Every change opens a PR for engineers to review, maintaining human ownership of the knowledge base.\n- **Major version history (optional).** When a major semver bump is detected, an additional step can update an architecture history log. Remove this step if you don't need it.\n\n## Origin\n\nThis pipeline was built at [Popsa](https://popsa.com) to keep engineering documentation in sync with a multi-repo codebase. You can read the full story in [I'd Rather Build the System](https://blog.popsa.com/id-rather-build-the-system/).\n\n## Licence\n\n[MIT](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpopsa-hq%2Fauto-docs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpopsa-hq%2Fauto-docs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpopsa-hq%2Fauto-docs/lists"}