Auto generate github actions document from yml file.
- Reusable Workflows
- Custom Actions
- Composite Actions
- Docker Container Actions
- Javascript Actions
- Make your awesome Custom Actions or Reusable Workflows on your repository.
- Use this reusable workflow in your repository.
- Please find a example of usage here.
For adding further documentation, comment annotation features are supported on the workflow file.
# | Annotation | value | description |
---|---|---|---|
1 | @example | Title with markdown value (e.g. ### Title) | @example can make examples with a code block and insert those comments under the each workflow title. |
1 | @note | Title with markdown value (e.g. ### Title) | @note can make notes with a raw markdown and insert those comments at the bottom of the generated document. |
- You can find examples for the usage of annotations below.
- 2022/08/10: First creation v0.0.1
- 2022/08/10: Readme update v0.0.2
using: node16
Auto documentation for Github Actions workflows
steps:
- id: documenter
name: "Generate document"
uses: gizumon/github-actions-documenter@main
steps:
- id: documenter
name: "Generate document"
uses: gizumon/github-actions-documenter@main
with:
target-filepaths: |
action.yml
.github/workflows/github-actions-documenter.yml
should-skip-generate-agenda: true
should-skip-generate-custom-actions: false
should-skip-generate-reusable-workflows: false
# | Required | Name | Default | Description |
---|---|---|---|---|
1 | target-filepaths | Target filepaths for generating Custom Actions and Reusable Workflows. If not specified, all Custom Actions and Reusable Workflows files in the repository will be documented. (default: "") |
||
2 | should-skip-generate-agenda | false | If true, skip generating Agenda document. (default: false) | |
3 | should-skip-generate-custom-actions | false | If true, skip generating Custom Actions document. (default: false) | |
4 | should-skip-generate-reusable-workflows | false | If true, skip generating Reusable Workflows document. (default: false) |
# | Name | Description |
---|---|---|
1 | output | GitHub Actions markdown documents including Custom Actions and Reusable Workflows |
2 | agenda-ca | Agenda for Custom Actions markdown documents |
3 | output-ca | Custom Actions markdown documents |
4 | agenda-rw | Agenda for Reusable Workflows markdown documents |
5 | output-rw | Reusable Workflows markdown documents |
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
name: "Advanced example"
on:
pull_request:
paths:
- '.github/workflows/*.yml'
jobs:
test:
uses: gizumon/github-actions-documenter/.github/workflows/github-actions-documenter.yml@main
with:
filepath: .github/docs/github-actions-doc.md
overwrite: true
make-pull-request: true
# | Required | Type | Name | Default | Description |
---|---|---|---|---|---|
1 | ✅ | string | filepath | README.md | Filepath to write the generated reusable workflow document. (default: README.md) |
2 | boolean | overwrite | false | If true, overwrite the filepath file. (default: false) | |
3 | boolean | make-pull-request | false | If true, make a pull request to ref branch. If false, directly push to ref branch. (default: false) |
# | Name | Description |
---|---|---|
1 | output | GitHub Actions markdown document (Reusable Workflow and Custom Actions) |
- push
- pull_request