Skip to main content

GitHub Action Integration

CI Dokumentor can be used directly as a GitHub Action in your workflows, making it easy to automatically generate and maintain documentation for your CI/CD components.

Usage​

- uses: hoverkraft-tech/ci-dokumentor@fe7b78e19572b70e2a5db7f2a61b99c70358061a # 0.1.2
  with:
    # Source manifest file path to handle (e.g. `action.yml`, `.github/workflows/ci.yml`).
    # This input is required.
    source: ""

    # Destination path for generated documentation (optional; destination is auto-detected if not specified by the adapter).
    destination: ""

    # Repository platform (auto-detected if not specified).
    repository: ""

    # CI/CD platform (`github-actions`, `gitlab-ci`, etc.).
    cicd: ""

    # Comma-separated list of sections to include.
    include-sections: ""

    # Comma-separated list of sections to exclude.
    exclude-sections: ""

    # Whether to perform a dry run (no files are written).
    # Default: `false`
    dry-run: "false"

    # Version to document (auto-detected if not specified).
    version: ""

    # JSON array of extra badges to include in the documentation.
    # Each badge should have `label`, `url`, and optional `linkUrl` properties.
    extra-badges: ""

    # Transform bare URLs to links.
    # Types: `auto` (autolinks), `full` (full links), `false` (disabled).
    #
    # Default: `auto`
    format-link: auto

    # The GitHub token used to fetch repository information.
    # Default: `${{ github.token }}`
    github-token: ${{ github.token }}

    # Version of CI Dokumentor to use. See https://github.com/hoverkraft-tech/ci-dokumentor/releases.
    # Default: `latest`
    ci-dokumentor-version: latest

Inputs​

InputDescriptionRequiredDefault
sourceSource manifest file path to handle (e.g. action.yml, .github/workflows/ci.yml).true-
destinationDestination path for generated documentation (optional; destination is auto-detected if not specified by the adapter).false-
repositoryRepository platform (auto-detected if not specified).false-
cicdCI/CD platform (github-actions, gitlab-ci, etc.).false-
include-sectionsComma-separated list of sections to include.false-
exclude-sectionsComma-separated list of sections to exclude.false-
dry-runWhether to perform a dry run (no files are written).falsefalse
versionVersion to document (auto-detected if not specified).false-
extra-badgesJSON array of extra badges to include in the documentation.false-
Each badge should have label, url, and optional linkUrl properties.
format-linkTransform bare URLs to links.falseauto
Types: auto (autolinks), full (full links), false (disabled).
github-tokenThe GitHub token used to fetch repository information.false${{ github.token }}
ci-dokumentor-versionVersion of CI Dokumentor to use. See https://github.com/hoverkraft-tech/ci-dokumentor/releases.falselatest

Outputs​

OutputDescription
destinationDestination path for generated documentation.

Examples​

Generate Documentation for Workflows​

- name: Generate Workflow Documentation
  uses: hoverkraft-tech/ci-dokumentor@fe7b78e19572b70e2a5db7f2a61b99c70358061a # 0.1.2
  with:
    source: ".github/workflows/ci.yml"

Advanced Usage with All Options​

The CLI accepts a single --source <file> per invocation. To generate documentation for multiple files in a workflow, run the action multiple times or script the Docker/CLI call for each file. Example using a shell step to process multiple manifest files:

- name: Generate Enhanced Documentation
  uses: hoverkraft-tech/ci-dokumentor@fe7b78e19572b70e2a5db7f2a61b99c70358061a # 0.1.2
  with:
    source: "action.yml"
    output: "docs/README.md"
    repository: "github"
    cicd: "github-actions"
    include-sections: "inputs,outputs,runs"
    exclude-sections: "examples"
    format-link: "full"

Dry-run Example​

To preview changes without modifying files, set the dry-run input to true. The action will pass --dry-run to the CLI and the core generator will produce a diff instead of writing files.

- name: Generate Documentation (dry-run)
  uses: hoverkraft-tech/ci-dokumentor@fe7b78e19572b70e2a5db7f2a61b99c70358061a # 0.1.2
  with:
    source: "action.yml"
    dry-run: "true"