From 9ab342dfd694c9c0603a73b56626492a13eec295 Mon Sep 17 00:00:00 2001 From: "yuito.watanabe" <72675978+wwwyo@users.noreply.github.com> Date: Sun, 25 Oct 2026 14:34:04 +0900 Subject: [PATCH 1/2] docs(skill): use dedicated App tokens for scheduled update PRs --- .agents/skills/skillctrl/evals/evals.json | 14 ++++++ .agents/skills/skillctrl/references/ci.md | 60 ++++++++++++++++++++--- docs/ja/skills/skillctrl/evals/evals.json | 14 ++++++ docs/ja/skills/skillctrl/references/ci.md | 53 ++++++++++++++++++-- 4 files changed, 132 insertions(+), 9 deletions(-) diff --git a/.agents/skills/skillctrl/evals/evals.json b/.agents/skills/skillctrl/evals/evals.json index 9dded27..2059461 100644 --- a/.agents/skills/skillctrl/evals/evals.json +++ b/.agents/skills/skillctrl/evals/evals.json @@ -88,6 +88,20 @@ "Runs git apply --check for a nonempty patch in the agent job against the same base state used by the publish job, rather than the already repaired checkout, and fails before handoff on validation errors.", "Anticipates large output from replaced adaptation or reverting entire imports; restricting input to diffs does not bound repair output." ] + }, + { + "id": 8, + "prompt": "Our gh-aw scheduled update pushes its branch with GITHUB_TOKEN, but gh pr create fails because Actions cannot create pull requests. We want CI and review bots to run automatically on the draft PR without enabling repository-wide Actions PR creation. Explain the setup and token boundaries without executing commands or editing files.", + "expected_output": "A dedicated, repository-scoped GitHub App token creates the draft PR while GITHUB_TOKEN still pushes the branch; verify that CI and review run on the PR head.", + "files": [], + "expectations": [ + "Reads references/ci.md and explains that the Actions PR creation setting is repository-wide, while GITHUB_TOKEN PR events can suppress automatic checks or require approval.", + "Recommends an App with only Contents read and Pull requests write, webhooks disabled, installation restricted to its owner and the selected repository.", + "Stores the Client ID in a repository variable and the private key in a repository secret; deletes the local key after registration and never commits it.", + "Mints the token immediately before trusted publication using SHA-pinned actions/create-github-app-token, client-id, private-key, explicit repositories: ${{ github.event.repository.name }} for strict mode, and permission-pull-requests: write.", + "Passes GH_TOKEN=\"$APP_TOKEN\" only to gh pr create; retains GITHUB_TOKEN with contents: write for branch pushes.", + "Verifies CI and review on the App-created draft PR and separately plans fresh checks for later GITHUB_TOKEN commits without granting this App Contents write." + ] } ] } diff --git a/.agents/skills/skillctrl/references/ci.md b/.agents/skills/skillctrl/references/ci.md index f65d2d6..9c80cbd 100644 --- a/.agents/skills/skillctrl/references/ci.md +++ b/.agents/skills/skillctrl/references/ci.md @@ -144,8 +144,9 @@ Keep credentials in the repository's secret management. Configure a fixed hash probe before agent execution so matching content never starts inference. Use [safe outputs](https://github.github.com/gh-aw/reference/safe-outputs/) for comments, accepted-lock publication to the PR branch, draft PR creation, -and check results. Restrict PR-check writes to the accepted lock; use trusted -repository checks for permitted paths and registered-original integrity. The +and check results. For scheduled draft PRs, configure the PR creation token as +described below, including in a custom safe-output publish job. Restrict PR-check +writes to the accepted lock; use trusted repository checks for permitted paths and registered-original integrity. The required result must refer to the commit actually verified, rather than an unreviewed newer head. @@ -169,8 +170,55 @@ Before relying on the workflows, exercise matching content, accepted drift, suspected violations, unknown decisions, and a scheduled update in Actions. Compilation alone does not establish that authentication or publication works. -Plan how a bot-written commit gets checked: pushes made with `GITHUB_TOKEN` -generally do not trigger another workflow run. Use an appropriate GitHub App -token or an explicit supported dispatch route, and verify the resulting checks -on the new commit. See [GitHub's trigger rules](https://docs.github.com/en/actions/how-tos/write-workflows/choose-when-workflows-run/trigger-a-workflow) +### Use a dedicated App token to create scheduled draft PRs + +When **Allow GitHub Actions to create and approve pull requests** is disabled, +`gh pr create` with `GITHUB_TOKEN` fails with +`GitHub Actions is not permitted to create or approve pull requests (createPullRequest)`. +Enabling that repository setting permits PR creation across workflows with +sufficient token permissions; it cannot be limited to one workflow. It also does +not ensure automatic CI and review: `GITHUB_TOKEN` events suppress follow-up runs +or require manual approval for supported PR events. + +Prefer a dedicated GitHub App installation token for PR creation: + +1. Create an App with only **Contents: Read-only** and **Pull requests: Read and + write** repository permissions. Disable webhooks, allow installation only on + its owning account, and install it with **Only select repositories** for the + target repository. +2. Store its Client ID in a repository variable (for example, + `SKILLCTRL_APP_CLIENT_ID`) and its generated `.pem` private key in a repository + secret (for example, `SKILLCTRL_APP_PRIVATE_KEY`). Delete the local key file + after registration; never commit it. +3. Immediately before the trusted publish step, mint a token scoped to the + current repository. In the workflow's publish job, use: + + ```yaml + - name: Mint the PR app token + id: app-token + uses: actions/create-github-app-token@64ab729a6294000f5aa4a4bc0b73d1f32bc45510 # v3.3.0 + with: + client-id: ${{ vars.SKILLCTRL_APP_CLIENT_ID }} + private-key: ${{ secrets.SKILLCTRL_APP_PRIVATE_KEY }} + repositories: ${{ github.event.repository.name }} + permission-pull-requests: write + - name: Publish the draft PR + env: + APP_TOKEN: ${{ steps.app-token.outputs.token }} + run: | + GH_TOKEN="$APP_TOKEN" gh pr create --draft --base "$DEFAULT_BRANCH" --head "$UPDATE_BRANCH" --title "chore(skills): update upstreams" --body-file "$REPORT_FILE" + ``` + + The publish job supplies `DEFAULT_BRANCH`, `UPDATE_BRANCH`, and `REPORT_FILE` + after verification and branch publication. Keep `repositories` explicit: + gh-aw strict mode rejects this action without that input. Pass `APP_TOKEN` + only to `gh pr create`; branch pushes can keep `GITHUB_TOKEN` with + `contents: write`, so the App needs no Contents write permission. + +Verify that opening the App-authored draft PR starts CI and review on its head. +For later bot-written commits, `GITHUB_TOKEN` pushes generally do not start +another workflow automatically. Use an appropriately permissioned App token or +an explicit supported dispatch route when those commits need fresh checks; +the PR-only App above cannot push. Verify checks on each new commit. See +[GitHub's trigger rules](https://docs.github.com/en/actions/how-tos/write-workflows/choose-when-workflows-run/trigger-a-workflow) and [gh-aw CI triggering](https://github.github.com/gh-aw/reference/triggering-ci/). diff --git a/docs/ja/skills/skillctrl/evals/evals.json b/docs/ja/skills/skillctrl/evals/evals.json index 57800e7..054fa32 100644 --- a/docs/ja/skills/skillctrl/evals/evals.json +++ b/docs/ja/skills/skillctrl/evals/evals.json @@ -88,6 +88,20 @@ "空でない patch に対し、agent job 内で、修正済みの checkout ではなく publish job と同じ基準状態に対して git apply --check を実行し、検証エラーなら引き渡す前に失敗にする。", "replaced 後の適応や取り込み全体を戻す修正で出力が大きくなることを想定する。入力を差分に絞っても修正出力のサイズに上限はつかないと説明する。" ] + }, + { + "id": 8, + "prompt": "gh-aw の定期更新では GITHUB_TOKEN で branch を push していますが、Actions に PR 作成が許可されておらず gh pr create が失敗します。repo 全体で Actions の PR 作成を有効にせず、draft PR の CI と review bot を自動起動したいです。コマンド実行や編集をせず、設定と token の使い分けを説明してください。", + "expected_output": "対象 repo に限定した専用 GitHub App token で draft PR を作り、branch の push は GITHUB_TOKEN を使う。PR の head で CI とレビューの起動を確認する。", + "files": [], + "expectations": [ + "references/ci.md を読み、Actions の PR 作成設定は repo 単位であることと、GITHUB_TOKEN の PR イベントではチェックの自動起動が抑止されるか承認が必要になることを説明する。", + "Contents read と Pull requests write だけの App を推奨し、Webhook を無効にし、install を owner と対象 repo に限定する。", + "Client ID を repo variable、秘密鍵を repo secret に登録し、登録後はローカルの秘密鍵を削除して commit しない。", + "信頼できる公開処理の直前で、SHA pin した actions/create-github-app-token に client-id・private-key・strict mode 用の明示的な repositories: ${{ github.event.repository.name }}・permission-pull-requests: write を指定して token を発行する。", + "GH_TOKEN=\"$APP_TOKEN\" は gh pr create にだけ渡し、branch の push は contents: write の GITHUB_TOKEN のままにする。", + "App が作った draft PR で CI・レビューを確認し、この App に Contents write を与えず、その後の GITHUB_TOKEN commit のチェック起動方法も別途設定する。" + ] } ] } diff --git a/docs/ja/skills/skillctrl/references/ci.md b/docs/ja/skills/skillctrl/references/ci.md index 01fbbe5..bab5604 100644 --- a/docs/ja/skills/skillctrl/references/ci.md +++ b/docs/ja/skills/skillctrl/references/ci.md @@ -134,6 +134,8 @@ upstream の新しい release だけを理由に、無関係な PR を失敗に 一致時に推論を起動しないよう、agent の実行前に固定の hash の事前判定を置く。 コメント、PR ブランチへの lock の保存、draft PR の作成、チェック結果には [safe outputs](https://github.github.com/gh-aw/reference/safe-outputs/) を使う。 +定期更新の draft PR は、custom safe-output publish job を使う場合も含め、 +後述の PR 作成用 token を設定する。 PR のチェックが書き込める範囲は受理済み lock に限り、変更可能なパスと登録済み原本の整合性は 信頼できる repo のチェックで検証する。必須チェックは、未検証の新しい head ではなく、 実際に確認した commit に対する結果として保存する。 @@ -156,8 +158,53 @@ agent job 内で、publish job が適用先にするのと同じ基準状態に 編集は Markdown に対して行い、YAML を再生成する。運用前に Actions 上で、一致・適合する不一致・ 違反の疑い・判断不能・定期更新を確認する。compile だけでは認証や公開の動作は確認できない。 -bot が書き戻した commit の検証方法も設定する。`GITHUB_TOKEN` による push では、 -通常は別の workflow が起動しない。適切な GitHub App token か、対応する明示的な dispatch を使い、 -新しい commit のチェックを確認する。 +### 定期更新の draft PR は専用 App の token で作る + +**Allow GitHub Actions to create and approve pull requests** が無効だと、 +`GITHUB_TOKEN` による `gh pr create` は +`GitHub Actions is not permitted to create or approve pull requests (createPullRequest)` +で失敗する。この repo 設定を有効にすると、十分な token 権限を持つ全 workflow で +PR を作成できるようになり、一つの workflow には限定できない。また、有効にしても +CI・レビューの自動起動は保証されない。`GITHUB_TOKEN` によるイベントは後続の実行を +抑止するか、対応する PR イベントで手動承認を必要とする。 + +PR の作成には、専用 GitHub App の installation token を推奨する。 + +1. Repository permissions は **Contents: Read-only** と **Pull requests: Read and + write** だけにする。Webhook を無効にし、install できる account は App の owner + だけに限定する。**Only select repositories** で対象 repo だけに install する。 +2. Client ID を repo の variable(例: `SKILLCTRL_APP_CLIENT_ID`)、生成した `.pem` + 秘密鍵を repo の secret(例: `SKILLCTRL_APP_PRIVATE_KEY`)に登録する。 + 登録後はローカルの秘密鍵ファイルを削除し、決して commit しない。 +3. 信頼できる publish step の直前で、現在の repo に限定した token を発行する。 + workflow の publish job では次のように設定する。 + + ```yaml + - name: Mint the PR app token + id: app-token + uses: actions/create-github-app-token@64ab729a6294000f5aa4a4bc0b73d1f32bc45510 # v3.3.0 + with: + client-id: ${{ vars.SKILLCTRL_APP_CLIENT_ID }} + private-key: ${{ secrets.SKILLCTRL_APP_PRIVATE_KEY }} + repositories: ${{ github.event.repository.name }} + permission-pull-requests: write + - name: Publish the draft PR + env: + APP_TOKEN: ${{ steps.app-token.outputs.token }} + run: | + GH_TOKEN="$APP_TOKEN" gh pr create --draft --base "$DEFAULT_BRANCH" --head "$UPDATE_BRANCH" --title "chore(skills): update upstreams" --body-file "$REPORT_FILE" + ``` + + publish job は検証と branch の公開を済ませたうえで、`DEFAULT_BRANCH`・ + `UPDATE_BRANCH`・`REPORT_FILE` を設定する。`repositories` は必ず明示する。 + この入力がないと gh-aw の strict mode は compile を拒否する。 + `APP_TOKEN` は `gh pr create` にだけ渡す。branch の push は `contents: write` の + `GITHUB_TOKEN` のままでよいため、App に Contents の write 権限は不要である。 + +App が作成した draft PR の head に対して、CI・レビューが起動することを確認する。 +その後 bot が書き戻す commit では、`GITHUB_TOKEN` の push は通常、別の workflow を +自動起動しない。新たなチェックが必要なら、適切な権限を持つ App token か、対応する +明示的な dispatch を使う。上記の PR 作成専用 App では push できない。 +新しい commit ごとにチェックを確認する。 [GitHub の起動規則](https://docs.github.com/en/actions/how-tos/write-workflows/choose-when-workflows-run/trigger-a-workflow) と [gh-aw の CI 起動](https://github.github.com/gh-aw/reference/triggering-ci/)を参照する。 From 42580d3df9fa135690133b5cec6b586430a26795 Mon Sep 17 00:00:00 2001 From: "yuito.watanabe" <72675978+wwwyo@users.noreply.github.com> Date: Sun, 25 Oct 2026 14:38:53 +0900 Subject: [PATCH 2/2] docs(skill): require custom publication for split credentials --- .agents/skills/skillctrl/evals/evals.json | 2 +- .agents/skills/skillctrl/references/ci.md | 10 ++++++---- docs/ja/skills/skillctrl/evals/evals.json | 2 +- docs/ja/skills/skillctrl/references/ci.md | 7 ++++--- 4 files changed, 12 insertions(+), 9 deletions(-) diff --git a/.agents/skills/skillctrl/evals/evals.json b/.agents/skills/skillctrl/evals/evals.json index 2059461..5c2300f 100644 --- a/.agents/skills/skillctrl/evals/evals.json +++ b/.agents/skills/skillctrl/evals/evals.json @@ -99,7 +99,7 @@ "Recommends an App with only Contents read and Pull requests write, webhooks disabled, installation restricted to its owner and the selected repository.", "Stores the Client ID in a repository variable and the private key in a repository secret; deletes the local key after registration and never commits it.", "Mints the token immediately before trusted publication using SHA-pinned actions/create-github-app-token, client-id, private-key, explicit repositories: ${{ github.event.repository.name }} for strict mode, and permission-pull-requests: write.", - "Passes GH_TOKEN=\"$APP_TOKEN\" only to gh pr create; retains GITHUB_TOKEN with contents: write for branch pushes.", + "Uses a custom trusted publish job for the token split, because the built-in create-pull-request handler uses its PR credential for Git operations too. Passes GH_TOKEN=\"$APP_TOKEN\" only to gh pr create; retains GITHUB_TOKEN with contents: write for branch pushes.", "Verifies CI and review on the App-created draft PR and separately plans fresh checks for later GITHUB_TOKEN commits without granting this App Contents write." ] } diff --git a/.agents/skills/skillctrl/references/ci.md b/.agents/skills/skillctrl/references/ci.md index 9c80cbd..055660a 100644 --- a/.agents/skills/skillctrl/references/ci.md +++ b/.agents/skills/skillctrl/references/ci.md @@ -144,9 +144,11 @@ Keep credentials in the repository's secret management. Configure a fixed hash probe before agent execution so matching content never starts inference. Use [safe outputs](https://github.github.com/gh-aw/reference/safe-outputs/) for comments, accepted-lock publication to the PR branch, draft PR creation, -and check results. For scheduled draft PRs, configure the PR creation token as -described below, including in a custom safe-output publish job. Restrict PR-check -writes to the accepted lock; use trusted repository checks for permitted paths and registered-original integrity. The +and check results. For scheduled draft PRs with the token split below, use a +custom trusted safe-output publish job: the built-in `create-pull-request` +handler also uses its PR credential for Git operations, so a PR-only App token +cannot publish its branch. Restrict PR-check writes to the accepted lock; use +trusted repository checks for permitted paths and registered-original integrity. The required result must refer to the commit actually verified, rather than an unreviewed newer head. @@ -191,7 +193,7 @@ Prefer a dedicated GitHub App installation token for PR creation: secret (for example, `SKILLCTRL_APP_PRIVATE_KEY`). Delete the local key file after registration; never commit it. 3. Immediately before the trusted publish step, mint a token scoped to the - current repository. In the workflow's publish job, use: + current repository. In the custom trusted publish job, use: ```yaml - name: Mint the PR app token diff --git a/docs/ja/skills/skillctrl/evals/evals.json b/docs/ja/skills/skillctrl/evals/evals.json index 054fa32..4e3c9b7 100644 --- a/docs/ja/skills/skillctrl/evals/evals.json +++ b/docs/ja/skills/skillctrl/evals/evals.json @@ -99,7 +99,7 @@ "Contents read と Pull requests write だけの App を推奨し、Webhook を無効にし、install を owner と対象 repo に限定する。", "Client ID を repo variable、秘密鍵を repo secret に登録し、登録後はローカルの秘密鍵を削除して commit しない。", "信頼できる公開処理の直前で、SHA pin した actions/create-github-app-token に client-id・private-key・strict mode 用の明示的な repositories: ${{ github.event.repository.name }}・permission-pull-requests: write を指定して token を発行する。", - "GH_TOKEN=\"$APP_TOKEN\" は gh pr create にだけ渡し、branch の push は contents: write の GITHUB_TOKEN のままにする。", + "組み込みの create-pull-request handler は PR 用の資格情報を Git 操作にも使うため、token の使い分けには信頼できる custom publish job を使う。GH_TOKEN=\"$APP_TOKEN\" は gh pr create にだけ渡し、branch の push は contents: write の GITHUB_TOKEN のままにする。", "App が作った draft PR で CI・レビューを確認し、この App に Contents write を与えず、その後の GITHUB_TOKEN commit のチェック起動方法も別途設定する。" ] } diff --git a/docs/ja/skills/skillctrl/references/ci.md b/docs/ja/skills/skillctrl/references/ci.md index bab5604..b593dc6 100644 --- a/docs/ja/skills/skillctrl/references/ci.md +++ b/docs/ja/skills/skillctrl/references/ci.md @@ -134,8 +134,9 @@ upstream の新しい release だけを理由に、無関係な PR を失敗に 一致時に推論を起動しないよう、agent の実行前に固定の hash の事前判定を置く。 コメント、PR ブランチへの lock の保存、draft PR の作成、チェック結果には [safe outputs](https://github.github.com/gh-aw/reference/safe-outputs/) を使う。 -定期更新の draft PR は、custom safe-output publish job を使う場合も含め、 -後述の PR 作成用 token を設定する。 +定期更新の draft PR で後述の token の使い分けを行うには、信頼できる custom +safe-output publish job を使う。組み込みの `create-pull-request` handler は +PR 用の資格情報を Git 操作にも使うため、PR 作成専用 App token では branch を公開できない。 PR のチェックが書き込める範囲は受理済み lock に限り、変更可能なパスと登録済み原本の整合性は 信頼できる repo のチェックで検証する。必須チェックは、未検証の新しい head ではなく、 実際に確認した commit に対する結果として保存する。 @@ -177,7 +178,7 @@ PR の作成には、専用 GitHub App の installation token を推奨する。 秘密鍵を repo の secret(例: `SKILLCTRL_APP_PRIVATE_KEY`)に登録する。 登録後はローカルの秘密鍵ファイルを削除し、決して commit しない。 3. 信頼できる publish step の直前で、現在の repo に限定した token を発行する。 - workflow の publish job では次のように設定する。 + 信頼できる custom publish job では次のように設定する。 ```yaml - name: Mint the PR app token