TOC Generator

Read this in other languages: English, 日本語.

これは目次を生成するGitHub Actionsです。
DocToc を実行し変更があればコミットします。

Table of Contents

• インストール
• スクリーンショット
• オプション
  • 個別に指定
• Action イベント詳細
  • 対象イベント
  • Conditions
• 補足
  • GITHUB_TOKEN
  • プルリクエストの作成
  • Context variables
  • Context PR variables
• 設定例
  • 例１
  • 例２
  • 例３
• Author

インストール

1. 目次の位置を指定 (option)

   <!-- START doctoc -->
   <!-- END doctoc -->

   詳細
2. workflow を設定
   例：.github/workflows/toc.yml

   on: push
   name: TOC Generator
   jobs:
     generateTOC:
       name: TOC Generator
       runs-on: ubuntu-latest
       steps:
         - uses: technote-space/toc-generator@v4

スクリーンショット

オプション

| name | description | default | e.g. | |:---|:---|:---|:---| |TARGET_PATHS|対象のファイルパス (カンマ区切り, 詳細)|README*.md|README*.md,CHANGELOG.md, .| |TOC_TITLE|目次タイトル|**Table of Contents**|''| |MAX_HEADER_LEVEL|Heading最大レベル (詳細)| |3| |CUSTOM_MODE|Customモードかどうか(生成例)|false|true| |CUSTOM_TEMPLATE|Customテンプレート(Customモード)|<p align="center">${ITEMS}</p>| | |ITEM_TEMPLATE|アイテムテンプレート(Customモード)|<a href="${LINK}">${TEXT}</a>| | |SEPARATOR|セパレータ(Customモード)|<span>|</span>| | |FOLDING|目次を折りたたみ式にするかどうか|false|true| |COMMIT_MESSAGE|コミットメッセージ|chore(docs): update TOC|docs: update TOC| |COMMIT_NAME|コミット時に設定する名前|${github.actor}| | |COMMIT_EMAIL|コミット時に設定するメールアドレス|${github.actor}@users.noreply.github.com| | |CREATE_PR|プルリクエストを作成するかどうか|false|true| |CHECK_ONLY_DEFAULT_BRANCH|デフォルトのブランチのみをチェックするかどうか|false|true| |PR_BRANCH_PREFIX|プルリクエストのブランチプリフィックス|toc-generator/| | |PR_BRANCH_NAME|プルリクエストのブランチ名Context variables|update-toc-${PR_ID}|toc-${PR_NUMBER}| |PR_TITLE|プルリクエストのタイトルContext variables|chore(docs): update TOC (${PR_MERGE_REF})|docs: update TOC| |PR_BODY|プルリクエストの本文Context PR variables|action.yml| | |PR_COMMENT_BODY|プルリクエストの本文(コメント用)Context PR variables|action.yml| | |PR_CLOSE_MESSAGE|プルリクエストを閉じるときのメッセージ|This PR has been closed because it is no longer needed.| | |TARGET_BRANCH_PREFIX|ブランチ名のフィルタ| |release/| |INCLUDE_LABELS|プルリクエストに付与されているかチェックするラベル| |Label1, Label2| |OPENING_COMMENT|開始コメント (DocToc以外のため)|<!-- toc | | |CLOSING_COMMENT|終了コメント (DocToc以外のため)|<!-- tocstop | | |SKIP_COMMENT|スキップコメントを変更 (default: <!-- DOCTOC SKIP )| |<!-- toc skip | |GITHUB_TOKEN|アクセストークン|${{github.token}}|${{secrets.ACCESS_TOKEN}}| |SIGNOFF| Signed-off-byを付与 | |true|

個別に指定

doctoc に使用されているオプションはコメントで値を指定することが可能です。
異なる設定で複数の目次を生成したい場合は以下のように個別に値を指定してください。

例：

<!-- START doctoc -->
<!-- param::isNotitle::true:: -->
<!-- param::isCustomMode::true:: -->

<!-- END doctoc -->

...

Action イベント詳細

対象イベント

| eventName: action | condition | |:---|:---| |push: *|condition1| |pull_request: [opened, synchronize, reopened, labeled, unlabeled]|condition2| |pull_request: [closed]|| |schedule, repository_dispatch, workflow_dispatch||

• 次のアクティビティタイプは明示的に指定する必要があります。 (詳細)
  • labeled, unlabeled, closed

Conditions

condition1

• ブランチへのプッシュ (タグのプッシュではない)
  • ブランチ名 (TARGET_BRANCH_PREFIX)

condition2

• 指定したラベルが付与されているかどうか (INCLUDE_LABELS)
• ブランチ名 (TARGET_BRANCH_PREFIX)

補足

GITHUB_TOKEN

GitHub Actions で提供されるGITHUB_TOKENは連続するイベントを作成する権限がありません。
したがって、プッシュによってトリガーされるビルドアクションなどは実行されません。

これはブランチプロテクションを設定していると問題になる場合があります。

もしアクションをトリガーしたい場合は代わりにpersonal access tokenを使用してください。

1. public_repo または repo の権限で Personal access token を生成
   (repo はプライベートリポジトリで必要です)
2. ACCESS_TOKENとして保存
3. GITHUB_TOKENの代わりにACCESS_TOKENを使用するように設定
   例：.github/workflows/toc.yml

   on: push
   name: TOC Generator
   jobs:
     generateTOC:
       name: TOC Generator
       runs-on: ubuntu-latest
       steps:
         - uses: technote-space/toc-generator@v4
           with:
             GITHUB_TOKEN: ${{ secrets.ACCESS_TOKEN }}

プルリクエストの作成

CREATE_PR に true を設定した場合は、プルリクエストが作成されます。

on: pull_request
name: TOC Generator
jobs:
  generateTOC:
    name: TOC Generator
    runs-on: ubuntu-latest
    steps:
      - uses: technote-space/toc-generator@v4
        with:
          CREATE_PR: true

closedアクティビティタイプが設定されている場合、このアクションは不要になったプルリクエストを閉じます。

on:
  pull_request:
    types: [opened, synchronize, reopened, closed]
name: TOC Generator
jobs:
  generateTOC:
    name: TOC Generator
    runs-on: ubuntu-latest
    steps:
      - uses: technote-space/toc-generator@v4

Context variables

| name | description | |:---|:---| | PR_NUMBER | pull_request.number (例：11) | | PR_NUMBER_REF | #${pull_request.number} (例：#11) | | PR_ID | pull_request.id (例：21031067) | | PR_HEAD_REF | pull_request.head.ref (例：change) | | PR_BASE_REF | pull_request.base.ref (例：main) | | PR_MERGE_REF | pull_request.base.ref (例：change -> main) | | PR_TITLE | pull_request.title (例：update the README with new information.) |

Payload example

Context PR variables

• Context variables

| name | description | |:---|:---| | PR_LINK | プルリクエストへのリンク | | COMMANDS_OUTPUT | TOC コマンドの結果 | | FILES_SUMMARY | 例：Changed 2 files | | FILES | 変更されたファイル一覧 |

設定例

例１

ブランチを制限しないでPush時にアクションを実行し直接コミット

on: push
name: TOC Generator
jobs:
  generateTOC:
    name: TOC Generator
    runs-on: ubuntu-latest
    steps:
      - uses: technote-space/toc-generator@v4

例２

release/ から始まるブランチのみを対象にPull Request更新時に実行しPull Requestを作成または更新

on:
  pull_request:
    types: [opened, synchronize, reopened, closed]
name: TOC Generator
jobs:
  generateTOC:
    name: TOC Generator
    runs-on: ubuntu-latest
    steps:
      - uses: technote-space/toc-generator@v4
        with:
          CREATE_PR: true
          TARGET_BRANCH_PREFIX: release/

例３

デフォルトブランチのみを対象にスケジュールでアクションを実行し直接コミット
（他のワークフローの起動のために作成したTokenを使用）

on:
  schedule:
    - cron: "0 23 * * *"
name: TOC Generator
jobs:
  generateTOC:
    name: TOC Generator
    runs-on: ubuntu-latest
    steps:
      - uses: technote-space/toc-generator@v4
        with:
          GITHUB_TOKEN: ${{ secrets.ACCESS_TOKEN }}
          CHECK_ONLY_DEFAULT_BRANCH: true

Author

GitHub (Technote)
Blog