Skip to content

Latest commit

 

History

History
267 lines (231 loc) · 11 KB

README.ja.md

File metadata and controls

267 lines (231 loc) · 11 KB
Raw

TOC Generator

CI Status codecov CodeFactor License: MIT

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

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

Table of Contents

Details

インストール

  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

スクリーンショット

behavior

オプション

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

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

condition2

補足

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

create pr

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

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