ログイン無料で始める

CI/CD 連携

Nolto の REST API を使って、CI/CD パイプラインからプランの登録やステータス更新、フェーズのテスト結果・最終レビュー結果の記録を自動化できます。

ℹ️

CI/CD では Personal API Token (nolto_user_*) を使ってください。 OAuth 2.1 はブラウザでの承認が必要なため、ヘッドレス環境には適しません。

GitHub Actions: プランの自動登録

リポジトリ内の Markdown ファイルをプランとして自動登録する例です。

name: Register Plan
on:
  push:
    branches: [main]
    paths:
      - 'plans/**/*.md'

jobs:
  register:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Register plans
        env:
          VIDOCS_TOKEN: ${{ secrets.VIDOCS_TOKEN }}
          PROJECT_ID: ${{ secrets.VIDOCS_PROJECT_ID }}
        run: |
          for file in plans/*.md; do
            [ -f "$file" ] || continue
            TITLE=$(head -1 "$file" | sed 's/^#\s*//')
            CONTENT=$(cat "$file")

            curl -s -X POST \
              -H "Authorization: Bearer $VIDOCS_TOKEN" \
              -H "Content-Type: application/json" \
              -d "$(jq -n \
                --arg title "$TITLE" \
                --arg content "$CONTENT" \
                --arg path "$file" \
                '{
                  plan: { title: $title, content: $content, status: "not_started" },
                  source: { kind: "file", path: $path }
                }')" \
              "https://nolto.app/api/projects/$PROJECT_ID/plans"
          done

シークレットの設定

GitHub リポジトリの Settings → Secrets and variables → Actions で以下を設定します:

  • VIDOCS_TOKEN — Personal API Token
  • VIDOCS_PROJECT_ID — 対象プロジェクトの UUID

GitHub Actions: デプロイ後のステータス更新

デプロイ成功時にプランのステータスを done に更新する例です。

name: Deploy and Update Plan
on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      # ... デプロイステップ ...

      - name: Update plan status
        if: success()
        env:
          VIDOCS_TOKEN: ${{ secrets.VIDOCS_TOKEN }}
          PROJECT_ID: ${{ secrets.VIDOCS_PROJECT_ID }}
          PLAN_ID: ${{ vars.CURRENT_PLAN_ID }}
        run: |
          curl -s -X POST \
            -H "Authorization: Bearer $VIDOCS_TOKEN" \
            -H "Content-Type: application/json" \
            -d '{"status": "done", "message": "CI/CD でデプロイ完了"}' \
            "https://nolto.app/api/projects/$PROJECT_ID/plans/$PLAN_ID/status"

GitHub Actions: フェーズのテスト結果を記録

テストジョブの結果を、対応するフェーズのテスト結果として記録する例です。合否を verdict に渡します（追記式なので再実行のたびにラウンドが増えます）。

name: Test and Record Result
on:
  pull_request:

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Run tests
        id: tests
        run: npm test

      - name: Record phase test result
        if: always()
        env:
          VIDOCS_TOKEN: ${{ secrets.VIDOCS_TOKEN }}
          PROJECT_ID: ${{ secrets.VIDOCS_PROJECT_ID }}
          PLAN_ID: ${{ vars.CURRENT_PLAN_ID }}
          PHASE_ID: ${{ vars.CURRENT_PHASE_ID }}
        run: |
          VERDICT=$([ "${{ steps.tests.outcome }}" = "success" ] && echo "passed" || echo "failed")
          curl -s -X POST \
            -H "Authorization: Bearer $VIDOCS_TOKEN" \
            -H "Content-Type: application/json" \
            -d "$(jq -n --arg v "$VERDICT" \
              '{ verdict: $v, summary: "CI でテストを実行" }')" \
            "https://nolto.app/api/projects/$PROJECT_ID/plans/$PLAN_ID/phases/$PHASE_ID/test-results"

if: always() で、テストが失敗しても結果（failed）を記録します。round を省略すると自動的に次のラウンド番号が割り当てられます。verdict には passed / failed / skipped を渡せます。

GitHub Actions: 最終レビュー結果（GO / NO-GO）を記録

リリース判定を記録する例です。手動承認（environment protection rules）を通過したら go を、失敗時に no_go を記録します。

      - name: Record final review
        if: always()
        env:
          VIDOCS_TOKEN: ${{ secrets.VIDOCS_TOKEN }}
          PROJECT_ID: ${{ secrets.VIDOCS_PROJECT_ID }}
          PLAN_ID: ${{ vars.CURRENT_PLAN_ID }}
        run: |
          VERDICT=$([ "${{ job.status }}" = "success" ] && echo "go" || echo "no_go")
          curl -s -X POST \
            -H "Authorization: Bearer $VIDOCS_TOKEN" \
            -H "Content-Type: application/json" \
            -d "$(jq -n --arg v "$VERDICT" \
              '{ verdict: $v, summary: "リリース判定" }')" \
            "https://nolto.app/api/projects/$PROJECT_ID/plans/$PLAN_ID/reviews"
ℹ️

テスト結果・レビュー結果はステータスとは独立した追記式の記録です。記録してもプラン・フェーズのステータスは変わりません（GO ＝ 完了ではありません）。 仕様は REST API と データモデル を参照してください。

ベストプラクティス

  • トークンのスコープ: CI 用のトークンには分かりやすい名前（例: github-actions-deploy）を付け、必要に応じて有効期限を設定してください。
  • エラーハンドリング: API が 4xx / 5xx を返した場合のハンドリングを追加してください。特に 429（レート制限）は Retry-After ヘッダーに従ってリトライするのが推奨です。
  • 冪等性: 同じプランを重複登録しないよう、source.hash にファイルの SHA256 ハッシュを渡すことを検討してください。
CI/CD 連携 | Nolto