@technote-space/toc-generator v4.3.1

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

スクリーンショット

オプション

個別に指定

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

例：

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

<!-- END doctoc -->

...

Action イベント詳細

対象イベント

• 次のアクティビティタイプは明示的に指定する必要があります。 (詳細)
  • 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 はプライベートリポジトリで必要です)
1. ACCESS_TOKENとして保存 1. 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

Payload example

Context PR variables

• Context variables

設定例

例１

ブランチを制限しないで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