Usage

Example action/workflow

Throughout the next pages, we will use a composite action action.yaml and a reusable workflow .github/workflows/example_workflow.yml as examples.

compsite action action.yaml

action.yaml

name: 'Example action'
description: 'An example `action.yaml` file for the purpose of documentation'
author: 'watermarkhu'

branding:
  icon: 'package'
  color: 'blue'

inputs:
  input-string:
    description: 'A string input parameter'
    required: true
  input-number:
    description: 'A numeric input parameter'
    required: false
    default: '42'
  input-boolean:
    description: 'A boolean input parameter'
    required: false
    default: 'false'

outputs:
  output-string:
    description: 'A string output from the action'
    value: 'result-value'
  output-number:
    description: 'A numeric output from the action'
    value: '123'

runs:
  using: 'composite'
  steps:
    - name: Execute action logic
      run: |
        echo "input-string=${{ inputs.input-string }}" >> $GITHUB_OUTPUT
        echo "output-number=123" >> $GITHUB_OUTPUT
        echo "output-json={\"key\": \"value\", \"number\": 456}" >> $GITHUB_OUTPUT
      shell: bash

reusable workflow .github/workflows/example_workflow.yml

.github/workflows/example_workflow.yml

name: 'Example workflow'
description: "This key is illegal but will still be parsed"

on:
  workflow_call:
    inputs:
      environment:
        description: 'Environment to deploy to'
        required: true
        type: string
      version:
        description: 'Version to deploy'
        required: false
        type: string
        default: 'latest'
      enable-notifications:
        description: 'Whether to send notifications. Requires [`SLACK_WEBHOOK`](#secrets.SLACK_WEBHOOK) to be set.'
        required: false
        type: boolean
        default: false
      parallel-jobs:
        description: 'Number of parallel jobs'
        required: false
        type: number
        default: 1
      configuration:
        description: 'JSON configuration object'
        required: false
        type: string
        default: '{}'
    secrets:
      API_KEY:
        description: 'API key for external service'
        required: true
      DATABASE_URL:
        description: 'Database connection string'
        required: false
      SLACK_WEBHOOK:
        description: 'Slack webhook URL for notifications'
        required: false
    outputs:
      deployment-id:
        description: 'ID of the created deployment'
        value: ${{ jobs.deploy.outputs.deployment-id }}
      deployment-url:
        description: 'URL of the deployment'
        value: ${{ jobs.deploy.outputs.deployment-url }}
      success:
        description: 'Whether the deployment was successful'
        value: ${{ jobs.deploy.outputs.success }}

permissions:
  contents: read
  deployments: write
  pull-requests: write
  issues: read

env:
  DEPLOYMENT_ENVIRONMENT: ${{ inputs.environment }}
  ENABLE_DEBUG: false

jobs:
  validate:
    name: 'Validate Inputs'
    runs-on: ubuntu-latest
    steps:
      - name: Validate environment
        run: |
          echo "Validating environment: ${{ inputs.environment }}"
          if [[ ! "${{ inputs.environment }}" =~ ^(development|staging|production)$ ]]; then
            echo "Error: Invalid environment specified"
            exit 1
          fi

      - name: Validate version
        run: |
          echo "Validating version: ${{ inputs.version }}"

      - name: Check secrets
        run: |
          if [[ -z "${{ secrets.API_KEY }}" ]]; then
            echo "Error: API_KEY secret is required"
            exit 1
          fi
          echo "All required secrets are available"

  deploy:
    name: 'Deploy Application'
    runs-on: ubuntu-latest
    needs: validate
    outputs:
      deployment-id: ${{ steps.deploy.outputs.deployment-id }}
      deployment-url: ${{ steps.deploy.outputs.deployment-url }}
      success: ${{ steps.deploy.outputs.success }}
    steps:
      - name: Setup deployment
        run: |
          echo "Setting up deployment for ${{ inputs.environment }}"
          echo "Version: ${{ inputs.version }}"
          echo "Parallel jobs: ${{ inputs.parallel-jobs }}"
          echo "Notifications enabled: ${{ inputs.enable-notifications }}"

      - name: Parse configuration
        run: |
          echo "Configuration: ${{ inputs.configuration }}"

      - name: Execute deployment
        id: deploy
        run: |
          deployment_id="reusable-deploy-$(date +%s)"
          deployment_url="https://${{ inputs.environment }}.example.com"

          echo "deployment-id=${deployment_id}" >> $GITHUB_OUTPUT
          echo "deployment-url=${deployment_url}" >> $GITHUB_OUTPUT
          echo "success=true" >> $GITHUB_OUTPUT

          echo "Deployment completed successfully"
          echo "ID: ${deployment_id}"
          echo "URL: ${deployment_url}"

  notify:
    name: 'Send Notifications'
    runs-on: ubuntu-latest
    needs: deploy
    if: ${{ inputs.enable-notifications }}
    steps:
      - name: Send Slack notification
        run: |
          echo "Sending Slack notification about deployment ${{ needs.deploy.outputs.deployment-id }}"

      - name: Create GitHub deployment
        run: |
          echo "Creating GitHub deployment status for ${{ needs.deploy.outputs.deployment-id }}"

Installation

This package is extension package to mkdocstrings, a framework for auto-documentation for various languages. Language support is inserted into the framework by providing handlers. The mkdocstrings-github package provides a GitHub handler.

You can install the GitHub handler by specifying it as a dependency:

pyproject.toml

# PEP 621 dependencies declaration
# adapt to your dependencies manager
[project]
dependencies = [
    "mkdocstrings-github>=0.X.Y",
]

The default mkdocstrings handler is the Python handler. You can change the default hanlder and set the GitHub handler as default be defining the default_handler configuration option of mkdocstrings in mkdocs.yml:

mkdocs.yml

plugins:
- mkdocstrings:
    default_handler: github

Injecting documentation

With the GitHub handler installed and configured as default handler, you can inject documentation for a GitHub action or a reusable workflow in your Markdown pages:

::: <path to action or workflow from the git root>

If another handler was defined as default handler, you can explicitely ask for the GitHub handler to be used when injecting documentation with the handler option:

::: <path to action or workflow from the git root>
    handler: github

The path to the action or workflow is consistent with how they are called in GitHub Actions. For actions, the path should the folder containing the action.yml or action.yaml file. The filename should not be included.

action.yaml or action.yml.github/actions/myaction/action.ymlaction/nested/in/directory/action.yaml

::: .

::: .github/actions/myaction

::: action/nested/in/directory

For reusable workflows, which are workflows that include the workflow_call trigger, the full path should be included.

.github/workflows/reusable_workflow.yaml.github/workflows/myworkflow.yml

::: .github/workflows/reusable_workflow.yaml

::: .github/workflows/myworkflow.yml

Linking

For every documented action or workflow, HTML tags are inserted on the page to allow linking with the action/workflow path as the id. Additionally, linking to action and workflow parameters, and cross-linking to other parameters, is possible with the parameters_anchors option.

Configuration

When installed, the Github handler can be configured in mkdocs.yml

mkdocs.yml

plugins:
- mkdocstrings:
    handlers:
      github:
        ... # The GitHub handler configuration

Global-only options

Some options are **global only, and go directly under the handler's name.

hostname

The hostname of the GitHub instance to use.

repo

The GitHub repository in the format owner/repo.

By default, the repository is inferred from the current git repository using the default origin remote. If it cannot be inferred, it must be set manually.

feather_icons_source

The source URL for Feather icons.

In certain enterprise environments, external CDN access may be restricted. In such cases, you can host the feather.min.js file locally and set this option to the local path or URL. See more information at https://github.com/feathericons/feather.

Global/local options

The other options can be used both globally and locally, under the options key. For example, globally:

mkdocs.yml

plugins:
- mkdocstrings:
    handlers:
      github:
        options:
          do_something: true

...and locally, overriding the global configuration:

docs/some_page.md

::: .github/workflows/reusable-workflow.yml
    handler: github
    options:
        do_something: true

These options affect how the documentation is collected from sources and rendered. See the following tables summarizing the options, and get more details for each option in the following pages:

• General options: Generic options that does not fit in the below catagories.
• Headings options: options related to the headings and the table of contents.
• Signature options: options related to the shown call signature.
• Parameters options: options related to the input (and output) parameters of the action or workflow.

The following are the available options for the GitHub handler. The options are loaded as a pydantic model, so they are type-checked and validated.

Show JSON schema:

{
  "description": "The following are the available options for the GitHub handler.\nThe options are loaded as a pydantic model, so they are type-checked and validated.",
  "properties": {
    "show_description": {
      "default": true,
      "description": "Whether to show the description in the documentation.",
      "title": "Show Description",
      "type": "boolean"
    },
    "description": {
      "default": "",
      "description": "A custom string to override the autogenerated description of the object.",
      "title": "Description",
      "type": "string"
    },
    "show_source": {
      "default": true,
      "description": "Whether to show the source link in the documentation.",
      "title": "Show Source",
      "type": "boolean"
    },
    "show_heading": {
      "default": true,
      "description": "Whether to show the heading in the documentation.",
      "title": "Show Heading",
      "type": "boolean"
    },
    "heading": {
      "default": "",
      "description": "A custom string to override the autogenerated heading of the object.",
      "title": "Heading",
      "type": "string"
    },
    "heading_level": {
      "default": 2,
      "description": "The initial heading level to use.",
      "title": "Heading Level",
      "type": "integer"
    },
    "show_branding": {
      "default": true,
      "description": "Whether to show the action branding (logo and color) in the documentation.",
      "title": "Show Branding",
      "type": "boolean"
    },
    "branding_icon": {
      "default": "",
      "description": "Custom icon from https://feathericons.com/ to use for the branding.",
      "title": "Branding Icon",
      "type": "string"
    },
    "branding_icon_color": {
      "default": "",
      "description": "Custom icon color for the feather icon.",
      "title": "Branding Icon Color",
      "type": "string"
    },
    "show_toc_entry": {
      "default": true,
      "description": "If the heading is not shown, at least add a ToC entry for it.",
      "title": "Show Toc Entry",
      "type": "boolean"
    },
    "toc_label": {
      "default": "",
      "description": "A custom string to override the autogenerated toc label of the root object.",
      "title": "Toc Label",
      "type": "string"
    },
    "show_signature": {
      "default": true,
      "description": "Whether to show the signature in the documentation.",
      "title": "Show Signature",
      "type": "boolean"
    },
    "signature_show_secrets": {
      "default": false,
      "description": "Whether to show secrets in the signature.",
      "title": "Signature Show Secrets",
      "type": "boolean"
    },
    "signature_show_permissions": {
      "default": true,
      "description": "Whether to show permissions in the workflow signature.",
      "title": "Signature Show Permissions",
      "type": "boolean"
    },
    "signature_version": {
      "default": "ref",
      "description": "The versioning scheme to use for the signature.\n\n        - `ref`: use the git ref (branch or tag) from which the workflow or action is run,\n        - `major`: use the latest release tag matching `vX` (e.g. `v1`, `v2`),\n        - `semver`: use the latest release tag matching `vX.X.X` (e.g. `v1.0.0`, `v2.1.3`),\n        - `string`: use the string provided in the [`signature_version_string`][mkdocstrings_handlers.github.config.GitHubOptions.signature_version_string] option.\n        ",
      "enum": [
        "ref",
        "major",
        "semver",
        "string"
      ],
      "title": "Signature Version",
      "type": "string"
    },
    "signature_version_string": {
      "default": "latest",
      "description": "The version string to use if [`signature_version`][mkdocstrings_handlers.github.config.GitHubOptions.signature_version] is set to `string`.",
      "title": "Signature Version String",
      "type": "string"
    },
    "show_inputs": {
      "default": true,
      "description": "Whether to show inputs in the documentation.",
      "title": "Show Inputs",
      "type": "boolean"
    },
    "show_inputs_only_required": {
      "default": false,
      "description": "Whether to show only required inputs in the documentation.",
      "title": "Show Inputs Only Required",
      "type": "boolean"
    },
    "show_outputs": {
      "default": false,
      "description": "Whether to show outputs in the documentation.",
      "title": "Show Outputs",
      "type": "boolean"
    },
    "show_secrets": {
      "default": true,
      "description": "Whether to show secrets in the documentation.",
      "title": "Show Secrets",
      "type": "boolean"
    },
    "show_secrets_only_required": {
      "default": false,
      "description": "Whether to show only required secrets in the documentation.",
      "title": "Show Secrets Only Required",
      "type": "boolean"
    },
    "parameters_order": {
      "default": "source",
      "description": "The parameters ordering to use.\n\n        - `alphabetical`: order by the parameters names,\n        - `source`: order parameters as they appear in the source file.\n        ",
      "enum": [
        "alphabetical",
        "source"
      ],
      "title": "Parameters Order",
      "type": "string"
    },
    "parameters_section_style": {
      "default": "table",
      "description": "The style used to render docstring sections.\n\n        - `table`: render parameters in a table,\n        - `list`: render parameters in a list.\n        ",
      "enum": [
        "table",
        "list"
      ],
      "title": "Parameters Section Style",
      "type": "string"
    },
    "parameters_anchors": {
      "default": true,
      "description": "Whether to add anchors to parameters in the documentation.",
      "title": "Parameters Anchors",
      "type": "boolean"
    }
  },
  "title": "GitHubOptions",
  "type": "object"
}

Fields:

• show_description (bool)
• description (str)
• show_source (bool)
• show_heading (bool)
• heading (str)
• heading_level (int)
• show_branding (bool)
• branding_icon (str)
• branding_icon_color (str)
• show_toc_entry (bool)
• toc_label (str)
• show_signature (bool)
• signature_show_secrets (bool)
• signature_show_permissions (bool)
• signature_version (SIGNATURE_VERSION)
• signature_version_string (str)
• show_inputs (bool)
• show_inputs_only_required (bool)
• show_outputs (bool)
• show_secrets (bool)
• show_secrets_only_required (bool)
• parameters_order (PARAMETERS_ORDER)
• parameters_section_style (PARAMETERS_SECTION_STYLE)
• parameters_anchors (bool)