# 与 CI/CD 集成

GitBook 可以与你现有的任何 CI/CD 流水线配合使用，用于管理你的 OpenAPI 规范。通过使用 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: 将 OpenAPI 发布到 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: 检出
        uses: actions/checkout@v4

      - name: 将规范文件发布到 GitBook
        run: |
          npx -y @gitbook/cli@latest openapi publish \
            --spec "$GITBOOK_SPEC_NAME" \
            --organization "$GITBOOK_ORGANIZATION_ID" \
            <规范文件路径>
```

{% endcode %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://gitbook.com/docs/documentation/zh/api-references/guides/support-for-ci-cd-with-api-blocks.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.