CI/CD 連携

CI/CD では Personal API Token を secret として渡し、nolto sync を実行します。nolto.json と .nolto/roadmaps/<slug>.json はあらかじめリポジトリへコミットしてください。

GitHub Actions

リポジトリの roadmap または関連文書が main branch に入ったときに同期する例です。

name: Sync Nolto roadmap

on:
  push:
    branches: [main]
    paths:
      - ".nolto/roadmaps/*.json"
      - "docs/plans/**/*.md"
      - "nolto.json"

jobs:
  sync:
    runs-on: ubuntu-latest
    permissions:
      contents: read
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - name: Sync roadmap
        env:
          NOLTO_TOKEN: ${{ secrets.NOLTO_TOKEN }}
        run: npx --yes @nolto/cli sync

GitHub の Settings → Secrets and variables → Actions に NOLTO_TOKEN を登録してください。

project binding

CI は nolto.json の projectId を同期先として使用します。

{
  "projectId": "550e8400-e29b-41d4-a716-446655440000"
}

このファイルに secret は含まれません。別の project へ誤送信しないよう、pull request で変更をレビューしてください。

競合時の扱い

Nolto は roadmap の updatedAt を比較します。サーバー側の方が新しい場合、同期は 409 Conflict で失敗します。CI で自動リトライして上書きせず、先行した変更をリポジトリへ取り込んでから再実行してください。

ベストプラクティス

• CI 専用の token 名と有効期限を設定する
• workflow の権限を contents: read に限定する
• nolto sync が非ゼロ終了したら job を失敗させる
• roadmap と参照文書を同じ commit で更新する
• token をローテーションしたら古い token を失効する