CI/CD 連携

Nolto の REST API を使って、CI/CD パイプラインからプランの登録やステータス更新を自動化できます。

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"

クォータの事前確認

大量のプランを一括登録する前に、残りの変換クォータを確認できます:

curl -s -H "Authorization: Bearer $VIDOCS_TOKEN" \
  https://nolto.app/api/usage | jq .

クォータが不足している場合は 402 が返ります。詳しくは レート制限・Tier を参照してください。

ベストプラクティス

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