stale表示だけで判断せず、同host・別machine・CIのactive runを確認します。
RUNBOOK
実行・運用
jobの投入、状態確認、再開、トラブル対応、PR確認、archiveを扱うための運用入口です。
このページの内容
日常の1サイクル
運用コマンドはmain checkoutから実行する
job ls、job show、job resumeなどはSpecRunnerのjob worktree内では拒否されます。表示されたhintに従い、main checkoutへ戻ります。
- 1未完了jobを一覧する
新しいrequestを始める前に、対応待ちとarchive待ちを確認します。
npx specrunner job ls - 2requestをvalidateして実行する
構文を確定してから、slugを指定してPipelineを開始します。
npx specrunner request validate <slug> - 3状態ごとの次の操作を行う
実行中は待機し、対応待ちはJob IDを固定して内容を確認してからresumeします。
npx specrunner job show <job-id> - 4PRを確認してarchiveする
checksと差分をレビューし、下記のslug一意性gateを通過してからmerge・cleanupします。
job ls --all --json → Job ID固定 → archive
job lsを運用の入口にする
既定では非終端jobだけを表示し、状態を5つの運用カテゴリへまとめます。archivedとcanceledを含める場合は--allを使います。
npx specrunner job ls
npx specrunner job ls --all
npx specrunner job ls --json| カテゴリ | 含まれる状態 | 運用判断 |
|---|---|---|
| 実行中 | running | stale表示でもrunner ownershipを確認。process生存中は待機 |
| 対応待ち | awaiting-resume | reasonを確認してresume |
| merge・archive待ち | awaiting-archive | PRを確認 |
| 失敗・停止 | failed / terminated | 原因を確認してresume |
| 終了済み | archived / canceled | 通常は操作不要 |
状態に応答する
status、停止step、logを確認してから再開します。
job showとverbose logを使い、同じslugをresumeします。
resumeの前に専用runbookを通します。 fresh checkoutではlocal sidecarがなく、job lsとjob resumeのstale判定が一致しない場合があります。別runnerが所有していないことまで確認します。
npx specrunner job show <job-id>
# /recovery の全ゲートがPASSした後だけ実行
npx specrunner job resume my-feature同じ原因を--forceで押し通さない
記録済みstepの直近3 outcomeがescalationまたはerrorの場合、通常のresumeは停止します。原因を変えずに--forceで押し通しません。
PR確認からarchiveまで
awaiting-archiveはPipelineが完走し、人間によるmerge判断を待つ状態です。--with-mergeはPR checksを待ち、squash mergeしてからcleanupします。
- 1PR差分を確認
requestのスコープと受け入れ基準に一致しているか。
- 2checksを確認
pendingなら待機、failedなら修正してから再実行。
- 3archiveを実行
change folderの移動をfeature branchへ記録してからmerge gateへ進む。
- 4状態を確認
Status: archivedで完了。
# mutation前にidentityとslugの一意性を固定
npx specrunner job ls --all --json
npx specrunner job show <job-id>
npx specrunner job archive --with-merge my-feature
# cleanup後はslugで表示し、出力されたJob IDを固定値と照合
npx specrunner job show my-feature
npx specrunner job statsarchive commandはslugを受け取ります。一覧で同じslugの非終端jobが意図した1件だけであり、そのJob IDが固定値と一致する場合だけ実行します。成功後のjob show <slug>が表示するJob IDも固定値と照合します。
archive記録とmergeの順序、PR確認項目はPR・merge・archive、停止理由ごとの再実行判断はトラブル対応へ進みます。Pipeline自体のresumeが必要な場合だけ再開と状態照合を使います。
GitHub Issue連携を使う場合
Issueをrequestの入口にする運用オプションです。承認ラベルが付くまで起動されず、inbox runが開始と再開をreconcileします。
| 目的 | 操作 |
|---|---|
| requestを投入 | Issue本文をrequest.md形式で記述 |
| 実行を承認 | specrunner-approvedラベルを付与 |
| escalationへ応答 | 通知への返信として/resume <指示> |
| 完了を受領 | 通知されたPRを確認し、mergeとarchiveを判断 |
npx specrunner request template
npx specrunner inbox run定期実行の前に認証を分けて確認する
cronやGitHub Actionsでは、対話セッションのkeychainを前提にしません。GitHub API、git transport、agent runtimeを別々に確認します。
| 層 | 役割 | 確認点 |
|---|---|---|
| GitHub API | Issue・PR操作 | GH_TOKEN / GITHUB_TOKEN |
| git transport | fetch・push | HTTPS originとpush権限 |
| agent runtime | agent session | schedulerから読めるtoken |
PATH=/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin
*/5 * * * * cd ~/path/to/repo && npx specrunner inbox run >> ~/.specrunner-inbox.log 2>&1認証変数とinbox設定の既定値はConfigurationを参照してください。