> For the complete documentation index, see [llms.txt](https://gitbook.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://gitbook.com/docs/documentation/zh/chuang-jian-nei-rong/openapi/guides/support-for-ci-cd-with-api-blocks.md).

# 与 CI/CD 集成

了解如何在 GitBook 中自动更新你的 OpenAPI 规范

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: 将 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: Checkout
        uses: actions/checkout@v4

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

{% endcode %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

```
GET https://gitbook.com/docs/documentation/zh/chuang-jian-nei-rong/openapi/guides/support-for-ci-cd-with-api-blocks.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.