📝

ワークフローのドキュメントを書こう [GitHub Actions]

2022/08/08に公開

概要

GitHub Actions のワークフローは .github/workflows/ の直下に YAML ファイルを置かないといけないので数が増えてくるとごちゃっとしがちです。
サブディレクトリ等で分類できるといいのですが今のところはできません。
なのでドキュメントを書いて整理しておきましょう。

ドキュメントの置き場所

.github/workflows/README.md に置くのが良さそうです。

注意

If a repository contains more than one README file, then the file shown is chosen from locations in the following order: the .github directory, then the repository's root directory, and finally the docs directory.

.github/README.md に置いてしまうとリポジトリ直下の README.md より優先されて表示されてしまうので避けておきましょう。

ドキュメントの内容

CI と CD で分類しておくと読みやすそうです。
数が多い場合はその下をもう少し細かく分類しても良さそうです。

ワークフローのコーディング規約もここに書いておくといいでしょう。
長くなりそうなら別ファイルに分けてリンクだけしておくのがいいかもしれません。

.github/workflows/README.md

# Workflows
## CI
### Client Test
### Server Test
### Code Generator
## CD
### Client Deploy
### Server Deploy
### Release custom action
## Coding Standards

トリガーが手動なのか自動なのかを明記しておくと分かりやすいと思います。

.github/workflows/README.md

### Release custom action
1. Manually dispatch `increment-version.yml` and it will create a PR.
2. Manually merge the PR.
3. Automatically trigger `draft-release.yml` and it will create a release.
4. Manually publish the release.
5. Automatically trigger `released.yml` and it will tweet.

例

この例では CI と CD にそれぞれ 1 つしか項目がないので中間の分類は省略しました。

余談

元々のきっかけはカスタムアクションのリリースフローをドキュメントのどこに書こうか迷ったことでした。（例示したリポジトリです）
以下の理由から最終的に .github/workflows/README.md になりました。

リポジトリ直下の README.md はアクションの利用者向けの情報だけにしたい
CONTRIBUTING.md は貢献者向けの情報にしたいので Issue の作り方や Fork して PR を送るところまでが対象（チーム開発の場合はここでもよかったかも）
CODE_OF_CONDUCT.md は行動規範なので違う
GitHub の枠組みにないファイルに置いてもいいけどちょっと微妙
リポジトリ直下かリリースワークフローの近くに置いておきたい
ワークフロー全体のドキュメントも兼ねられる

概要

ドキュメントの置き場所

注意

ドキュメントの内容

例

余談

Discussion