Skip to content

General options¤

Example action/workflow
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 }}"

show_description ¤

Whether to show the description in the documentation.

Preview

Example action ¤

- uses: watermarkhu/mkdocstrings-github@v1
  with:
    input-string: ''

An example action.yaml file for the purpose of documentation

Inputs: ¤

Name Description Default
input-string

A string input parameter
input-number

A numeric input parameter

 42
input-boolean

A boolean input parameter

 false
Source of watermarkhu/mkdocstrings-github@v1 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
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

Example action ¤

- uses: watermarkhu/mkdocstrings-github@v1
  with:
    input-string: ''

Inputs: ¤

Name Description Default
input-string

A string input parameter
input-number

A numeric input parameter

 42
input-boolean

A boolean input parameter

 false
Source of watermarkhu/mkdocstrings-github@v1 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
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

description ¤

A custom string to override the autogenerated description of the object.

Preview

Example action ¤

- uses: watermarkhu/mkdocstrings-github@v1
  with:
    input-string: ''

An example action.yaml file for the purpose of documentation

Inputs: ¤

Name Description Default
input-string

A string input parameter
input-number

A numeric input parameter

 42
input-boolean

A boolean input parameter

 false
Source of watermarkhu/mkdocstrings-github@v1 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
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

Example action ¤

- uses: watermarkhu/mkdocstrings-github@v1
  with:
    input-string: ''
A custom description

Inputs: ¤

Name Description Default
input-string

A string input parameter
input-number

A numeric input parameter

 42
input-boolean

A boolean input parameter

 false
Source of watermarkhu/mkdocstrings-github@v1 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
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

show_source ¤

Whether to show the source link in the documentation.

Preview

Example action ¤

- uses: watermarkhu/mkdocstrings-github@v1
  with:
    input-string: ''

An example action.yaml file for the purpose of documentation

Inputs: ¤

Name Description Default
input-string

A string input parameter
input-number

A numeric input parameter

 42
input-boolean

A boolean input parameter

 false
Source of watermarkhu/mkdocstrings-github@v1 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
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

Example action ¤

- uses: watermarkhu/mkdocstrings-github@v1
  with:
    input-string: ''

An example action.yaml file for the purpose of documentation

Inputs: ¤

Name Description Default
input-string

A string input parameter
input-number

A numeric input parameter

 42
input-boolean

A boolean input parameter

 false