{"id":51061063,"url":"https://github.com/smol-utils/actiondoc","last_synced_at":"2026-06-23T02:01:11.231Z","repository":{"id":362916498,"uuid":"1247932111","full_name":"smol-utils/actiondoc","owner":"smol-utils","description":"Generate Markdown docs for GitHub Actions workflows and actions: call graphs, secret/permission inventories, and reusable-workflow contracts.","archived":false,"fork":false,"pushed_at":"2026-06-15T02:57:38.000Z","size":393,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-15T04:12:03.885Z","etag":null,"topics":["ci-cd","cli","devops","documentation","documentation-generator","github-action","golang","workflows"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"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/smol-utils.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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-05-24T01:10:57.000Z","updated_at":"2026-06-15T02:57:41.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/smol-utils/actiondoc","commit_stats":null,"previous_names":["smol-utils/actiondoc"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/smol-utils/actiondoc","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smol-utils%2Factiondoc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smol-utils%2Factiondoc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smol-utils%2Factiondoc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smol-utils%2Factiondoc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/smol-utils","download_url":"https://codeload.github.com/smol-utils/actiondoc/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smol-utils%2Factiondoc/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34672250,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-23T02:00:07.161Z","response_time":65,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["ci-cd","cli","devops","documentation","documentation-generator","github-action","golang","workflows"],"created_at":"2026-06-23T02:01:09.547Z","updated_at":"2026-06-23T02:01:11.221Z","avatar_url":"https://github.com/smol-utils.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# actiondoc\n\n\u003e Generate documentation for GitHub Actions workflows using JSDoc-style comments.\n\nactiondoc reads GitHub Actions workflow (`.github/workflows/*.yml`) and action files\n(`action.yml`), extracts both native YAML properties and ActionDoc comment tags, and\ngenerates Markdown documentation.\n\nFor the comment standard, see [spec/actiondoc-spec.md](spec/actiondoc-spec.md).\nFor a detailed history of changes, see [CHANGELOG.md](CHANGELOG.md).\n\n---\n\n## Quick Start\n\n```bash\n# Install from source\ngo install github.com/smol-utils/actiondoc@latest\n\n# Generate docs for all workflows in the current repo\nactiondoc generate\n\n# Generate for a specific file\nactiondoc generate .github/workflows/ci.yml\n\n# Write to a file instead of stdout\nactiondoc generate -o WORKFLOWS.md\n```\n\n### Before / After\n\n**Your workflow (input):**\n\n```yaml\n# @desc Deploy the application to production.\n# @secret AWS_ACCESS_KEY_ID - AWS credentials for deployment\n# @secret AWS_SECRET_ACCESS_KEY - AWS credentials for deployment\nname: Deploy\n\non:\n  push:\n    branches: [main]\n\njobs:\n  # @desc Build and push the Docker image to ECR.\n  # @env ECR_REGISTRY - Must be set in repository variables\n  build:\n    name: Build Image\n    runs-on: ubuntu-latest\n    steps:\n      - name: Checkout\n        uses: actions/checkout@v4\n      - name: Build and push\n        run: docker build -t $ECR_REGISTRY/app .\n```\n\n**Generated docs (output):**\n\n```markdown\n# Deploy\n\nDeploy the application to production.\n\n| Property | Value |\n|----------|-------|\n| File | `deploy.yml` |\n| Triggers | `push` |\n\n## Secrets\n\n| Name | Type | Description |\n|------|------|-------------|\n| `AWS_ACCESS_KEY_ID` | - | AWS credentials for deployment |\n| `AWS_SECRET_ACCESS_KEY` | - | AWS credentials for deployment |\n\n## Jobs\n\n### Build Image (`build`)\n\nBuild and push the Docker image to ECR.\n\n| Property | Value |\n|----------|-------|\n| Runs on | `ubuntu-latest` |\n\n**Environment Variables:**\n\n| Name | Type | Description |\n|------|------|-------------|\n| `ECR_REGISTRY` | - | Must be set in repository variables |\n```\n\n### Call graphs and cross-file requirements\n\nThe bigger win is *across* files. Pointed at a `.github/workflows` directory, actiondoc\nfollows `uses:` into reusable workflows and composite actions, then rolls up every secret\nand permission the whole chain needs -- the question a security review or a new hire asks\nfirst.\n\nA `release.yml` that calls a reusable `publish.yml` and a local `notify` action produces:\n\n````markdown\n## Call graph (rooted at this workflow)\n\n```\nrelease.yml [push]\n+-- publish (uses publish.yml)\n+-- announce / Notify (uses ./.github/actions/notify)\n```\n\n## Transitive requirements (from full call graph)\n\nSecrets referenced (literal names): `NPM_TOKEN`, `SLACK_WEBHOOK_URL`, `npm-token`\n\nPermissions declared across the chain: `contents: read`, `id-token: write (OIDC)`\n````\n\nFor the full output on real-world repositories (Airflow, jreleaser, and more), see\n[`dogfood/snapshots/`](dogfood/snapshots).\n\n---\n\n## Comment Tags\n\nActionDoc uses JSDoc-style comments placed above the YAML node they document. Only\nuse tags for information that can't be inferred from the YAML itself -- names, dependencies,\nand runner info are extracted automatically.\n\n| Tag | Purpose | Example |\n|-----|---------|---------|\n| `@desc` | Description (multi-line) | `@desc Build and deploy the app.` |\n| `@secret` | Required secret | `@secret AWS_KEY - AWS access key` |\n| `@input` | Workflow input | `@input env {string} - Target environment` |\n| `@env` | External env var | `@env DB_URL - Connection string` |\n| `@output` | Produced output | `@output tag {semver} - Image tag` |\n| `@deprecated` | Deprecation notice | `@deprecated Use deploy-v2 instead.` |\n| `@see` | Related link | `@see https://docs.example.com/deploy` |\n| `@since` | Version introduced | `@since v2.0.0` |\n| `@example` | Usage example (multi-line) | `@example` followed by indented lines |\n\nTags can be placed at three levels: above the first key (workflow-level), above a job\nkey (job-level), or above a step entry (step-level).\n\nFor the full specification, see [spec/actiondoc-spec.md](spec/actiondoc-spec.md).\n\n---\n\n## Usage\n\n```bash\n# Markdown to stdout (default)\nactiondoc generate\n\n# JSON output for tooling integration\nactiondoc generate --json\n\n# Specific file or directory\nactiondoc generate .github/workflows/deploy.yml\nactiondoc generate .github/workflows/\n\n# Write to file\nactiondoc generate -o docs/WORKFLOWS.md\n\n# Version\nactiondoc version\n```\n\n### Options\n\n| Flag | Default | Description |\n|------|---------|-------------|\n| `-o` | stdout | Write output to a file |\n| `--json` | false | Output JSON instead of Markdown |\n| `--repo` | auto-detected | Scanned repository identity as `owner/repo` (see [Repository identity](#repository-identity)) |\n| path (positional) | `.github/workflows` | File or directory to process |\n\n### Repository identity\n\nA repository often calls its own reusable workflows in the cross-repo form\n`owner/repo/.github/workflows/x.yml@ref` so the `@ref` pin selects a branch or tag. To tell\nthose self-calls apart from genuinely external workflows, actiondoc needs to know the\nscanned repository's identity. It is resolved in this order:\n\n1. The `--repo owner/repo` flag.\n2. The `GITHUB_REPOSITORY` environment variable (set automatically inside GitHub Actions).\n3. The `origin` git remote of the scanned path, if it is a GitHub URL.\n\nWhen none of these resolve, the identity is unknown and every `owner/repo` reference is\ntreated as **external** (the safe default): it is never linked to a same-named local\nworkflow, so cross-repo calls are not misreported as local. Set `--repo` to restore\nself-call resolution when running outside the repository or its CI.\n\n---\n\n## Install\n\n### From source (requires Go 1.22+)\n\n```bash\ngo install github.com/smol-utils/actiondoc@latest\n```\n\n### From GitHub Releases\n\nDownload a pre-built binary from the\n[Releases](https://github.com/smol-utils/actiondoc/releases) page.\n\n### Build locally\n\n```bash\ngit clone https://github.com/smol-utils/actiondoc.git\ncd actiondoc\nmake build\n./actiondoc generate\n```\n\n---\n\n## Development\n\n```bash\nmake help       # Show all available targets\nmake build      # Build the binary\nmake test       # Run all tests\nmake lint       # Run go vet\nmake ci         # Lint + test (local CI check)\nmake demo       # Run against the sample workflow\nmake golden     # Regenerate the golden test file\nmake clean      # Remove build artifacts\n```\n\n---\n\n## FAQ\n\n**Why not just read the YAML directly?**\n\nYou can, but large repos accumulate dozens of workflow files with hundreds of steps. The\nbiggest pain point is figuring out which secrets and environment variables need to be\nconfigured before a workflow will run. ActionDoc surfaces that information in one place.\n\n---\n\n**What happens if I don't add any ActionDoc comments?**\n\nThe tool still works. It extracts names, triggers, job dependencies, runner info, and\nstep actions from the YAML itself. Comments add descriptions and surface hidden\nrequirements (secrets, env vars) -- but they're optional.\n\n---\n\n**How is this different from action-docs?**\n\nBoth tools document `action.yml` and workflow files. The differences are footprint and\nthe comment tag system:\n\n- action-docs extracts structured YAML fields (inputs, outputs, description) from both\n  file types.\n- actiondoc does the same, plus supports JSDoc-style comment tags (`@secret`, `@env`,\n  `@deprecated`, `@example`, etc.) for documenting things the YAML can't express --\n  like which secrets need to be configured before a workflow will run.\n\n|  | actiondoc | action-docs |\n|--|-----------|-------------|\n| Workflows | Yes + comment tags | Yes |\n| Actions (`action.yml`) | Yes + comment tags | Yes |\n| Comment tag system | @desc, @secret, @env, @input, @output, @deprecated, @see, @since, @example | No |\n| Language | Go | Node.js |\n| Direct deps | 1 | 6 |\n| Transitive deps | 0 | 28 |\n| Runtime needed | None (static binary) | Node.js |\n| Install | Download binary or `go install` | `npm install` |\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsmol-utils%2Factiondoc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsmol-utils%2Factiondoc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsmol-utils%2Factiondoc/lists"}