Github Actionsのドキュメントを自動生成する

概要

Github Actionsのドキュメントを自動生成する方法についてご紹介します！
https://github.com/gizumon/github-actions-documenter#github-actions-documenter

対象

ターゲットユーザー🙎‍♂️

• Custom Actions / Reusable Workflowsを
  • 作ってみたけど、ドキュメント作ってない、、、
  • 作ってみたけど、ドキュメント作るのめんどくさかった、、、
  • 作っているけど、ドキュメントフォーマットがばらばら、、、
  • これからたくさん作る機会がありそう

対応ワークフロー📄

Github Actionsで再利用可能な部品を作成する、下記ドキュメントの自動生成に対応しています。

• Custom Actions
• Reusable Workflows
  • Docker Container Action
  • Javascript Action
  • Composite Action

対応機能🛠

• ① ymlファイルからマークダウンドキュメントの自動生成
  • アノテーション(@)を使って、ドキュメントにサンプル(@example)や注釈(@note)を追加することも可能です。(例)
  • 生成されるドキュメントのフォーマットはこちらを参照ください。
• ② 生成したマークダウンドキュメントを指定したファイルへ出力
  • 既存のファイルへの追加するか、新規ファイルへの上書きするかなどを指定することができます。
• ③　出力したファイルをコミット
• ④　新規プルリクエストの作成
  • 変更コミットの新規プルリクエストを作成することができます。
    • プルリクエストを作成しない場合は、対象ブランチに変更が追加されます。

使い方

自動生成したいymlが存在するリポジトリに下記の様なワークフローを追加ください。(追加例)

使い方サンプル

name: "Basic Sample"
on:
  push:
    branches:
      - main
    paths:
      - '*/action.yml'
      - '*/action.yaml'
      - '.github/workflows/*.yml'
  pull_request:
    paths:
      - '*/action.yml'
      - '*/action.yml'
      - '.github/workflows/*.yml'

jobs:
  documentation:
    uses: gizumon/github-actions-documenter/.github/workflows/github-actions-documenter.yml@main
    with:
      filepath: README.md

なお、GHE上などで、Reusable Workflowsを呼び出せない場合にはこちらのワークフローをコピーして、呼び出せる箇所に配置して使って頂ければと思います。

今のところ、Custom Actions内では、ドキュメントの生成のみしか対応しておらず、ワークフロー内でファイルへの追加(or 生成)とコミットを実行しています。
将来的にはこちらもCustom Actionsに統合していければと思っていますが、一旦上記の様に使って頂ければと思います。

サポートインターフェース

Reusable Workflowは下記のインターフェースをサポートしています。(最新の情報は、こちらをご確認ください。)

ワークフロー呼び出し例

    uses: gizumon/github-actions-documenter/.github/workflows/github-actions-documenter.yml@main
    with:
      filepath: README.md
      overwrite: true
      make-pull-request: true

#	必須	名前	説明
1	✅	filepath	生成したドキュメントを書き込むファイルパス(デフォルト: README.md)
2		overwrite	上書きフラグ。trueの場合、ファイルは上書きされます。falseの場合、ファイルに追記されます。(デフォルト: false)
3		make-pull-request	プルリクエスト作成フラグ。trueの場合、refブランチへ新規プルリクエストを作成します。falseの場合、refブランチへ直接プッシュします。(デフォルト: false)

生成ドキュメントイメージ

入力引数 (on.workflow_call.inputs)

対象yml

...
on:
  workflow_call:
    inputs:
      filepath:
        required: true
        type: string
        default: README.md
        description: "Filepath to write the generated reusable workflow document. (default: README.md)"
      overwrite:
        required: false
        type: boolean
        default: false
        description: "If true, overwrite the filepath file. (default: false)"
      make-pull-request:
        required: false
        type: boolean
        default: false
        description: "If true, make a pull request to ref branch. If false, directly push to ref branch. (default: false)"
...

↓ 生成マークダウン ↓

出力引数 (on.workflow_call.outputs)

対象yml

...
on:
  workflow_call:
    ...
    outputs:
      output:
        description: "GitHub Actions markdown document (Reusable Workflow and Custom Actions)"
        value: "${{ jobs.documentation.outputs.output }}"
...

↓ 生成マークダウン ↓

サンプル例 (comment:@example)

対象comment

# @example=### Example1: Basic example
# name: "Basic example"
# on:
#   pull_request:
#     paths:
#       - '.github/workflows/*.yml'
# jobs:
#   test:
#     uses: gizumon/github-actions-documenter/.github/workflows/github-actions-documenter.yml@main
#     with:
#       filepath: README.md

↓ 生成マークダウン ↓

注釈 (comment:@note)

対象comment

# @note=### Support events
# - push
# - pull_request

↓ 生成マークダウン ↓

最後に

• 不具合やご要望がありましたら、こちらでIssueを発行して頂けるととってもありがたいです🙇‍♂️
• まだまだ私自身Github Actionsお勉強中のため、フィードバックありましたらどしどしコメントお願いします！
  • 使い方等分からない点などもお気軽にコメント頂ければと思います!

---

https://github.com/gizumon
https://twitter.com/gizumon5