📝
Github Actionsのドキュメントを自動生成する
概要
Github Actionsのドキュメントを自動生成する方法についてご紹介します!
対象
ターゲットユーザー🙎♂️
-
Custom Actions / Reusable Workflowsを
- 作ってみたけど、ドキュメント作ってない、、、
- 作ってみたけど、ドキュメント作るのめんどくさかった、、、
- 作っているけど、ドキュメントフォーマットがばらばら、、、
- これからたくさん作る機会がありそう
対応ワークフロー📄
Github Actionsで再利用可能な部品を作成する、下記ドキュメントの自動生成に対応しています。
- Custom Actions
-
Reusable Workflows
- Docker Container Action
- Javascript Action
- Composite Action
対応機能🛠
- ① ymlファイルからマークダウンドキュメントの自動生成
-
② 生成したマークダウンドキュメントを指定したファイルへ出力
- 既存のファイルへの追加するか、新規ファイルへの上書きするかなどを指定することができます。
- ③ 出力したファイルをコミット
-
④ 新規プルリクエストの作成
- 変更コミットの新規プルリクエストを作成することができます。
- プルリクエストを作成しない場合は、対象ブランチに変更が追加されます。
- 変更コミットの新規プルリクエストを作成することができます。
使い方
自動生成したい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を呼び出せない場合にはこちらのワークフローをコピーして、呼び出せる箇所に配置して使って頂ければと思います。
サポートインターフェース
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お勉強中のため、フィードバックありましたらどしどしコメントお願いします!
- 使い方等分からない点などもお気軽にコメント頂ければと思います!
Discussion