# CI/CDとの統合

GitBook は、OpenAPI 仕様の管理に既に使用している任意の CI/CD パイプラインと連携できます。GitBook CLI を使用することで、API リファレンスの更新を自動化できます。

### 仕様ファイルをアップロードする

OpenAPI 仕様が CI プロセス中に生成される場合、ビルド環境から直接アップロードできます：

```bash
# GitBook の API トークンを環境変数として設定
export GITBOOK_TOKEN=<api-token>

gitbook openapi publish \
  --spec spec_name \
  --organization organization_id \
  example.openapi.yaml
```

### 新しいソース URL を設定するか更新をトリガーする

OpenAPI 仕様が URL にホストされている場合、GitBook は自動的に更新をチェックします。リリース後などに更新を強制するには、次を実行します：

```bash
# GitBook の API トークンを環境変数として設定
export GITBOOK_TOKEN=<api-token>

gitbook openapi publish \
  --spec spec_name \
  --organization organization_id \
  https://api.example.com/openapi.yaml
```

### GitHub Actions で仕様を更新する

OpenAPI 仕様を公開するワークフローを設定する場合、リポジトリで次の手順を完了してください：

1. リポジトリで「Settings → Secrets and variables → Actions」に移動します。
2. シークレットを追加： `GITBOOK_TOKEN` （あなたの GitBook API トークン）。
3. 変数を追加する（またはワークフローにハードコードする）：
   * `GITBOOK_SPEC_NAME` → GitBook 内のあなたの仕様の名前
   * `GITBOOK_ORGANIZATION_ID` → あなたの GitBook 組織 ID
4. ワークフローファイルを次の名前で保存： `.github/workflows/gitbook-openapi-publish.yml`.
5. 変更を “main” にプッシュする（またはワークフローを手動で実行する）。

その後、このアクションを使用して仕様を更新できます：

{% code title=".github/workflows/gitbook-openapi-publish.yml" %}

```yaml
name: Publish OpenAPI to GitBook

on:
  push:
    branches: [ "main" ]
    paths:
      - "**/*.yaml"
      - "**/*.yml"
      - "**/*.json"
  workflow_dispatch:

jobs:
  publish:
    runs-on: ubuntu-latest
    env:
      # 必須のシークレット
      GITBOOK_TOKEN: ${{ secrets.GITBOOK_TOKEN }}
      # 可能ならリポジトリ/組織の変数を優先；必要ならインライン文字列にフォールバック
      GITBOOK_SPEC_NAME: ${{ vars.GITBOOK_SPEC_NAME }}
      GITBOOK_ORGANIZATION_ID: ${{ vars.GITBOOK_ORGANIZATION_ID }}

    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Publish spec file to GitBook
        run: |
          npx -y @gitbook/cli@latest openapi publish \
            --spec "$GITBOOK_SPEC_NAME" \
            --organization "$GITBOOK_ORGANIZATION_ID" \
            <path_to_spec>
```

{% endcode %}