using-bitrise-ci

使用 Bitrise CI

目录

• 工具（身份验证、MCP、API、CLI）
• 核心概念
• 创建项目
• 使用 bitrise.yml（结构、组件、Docker 容器）
• 排查构建问题

自动化访问

身份验证

通过自动化方式（API、MCP 等）与 Bitrise 交互需要访问令牌。用户可以创建个人或工作区访问令牌。令牌应妥善安全地存储。

MCP 服务

Bitrise MCP 服务可在线使用，地址为 https://github.com/bitrise-io/bitrise-mcp，也可以在本地运行。它需要通过 Authorization: Bearer {token} 标头使用令牌进行身份验证。如果 MCP 服务可用，请优先使用它，而不是 API 或其他工具。

API

Bitrise REST API 可用于管理各种 Bitrise 资源。详细参考文档请见此处。API 需要使用 PAT 进行身份验证，并通过 Authorization: {PAT} 标头传递（不带 Bearer）。

CLI

Bitrise CLI 适用于本地环境。它不会与 Bitrise 资源交互，但可以帮助编辑和验证 bitrise.yml，并支持在本地运行工作流。它支持 Mac 和 Linux。

安装时，使用 brew install bitrise，或查看 Releases 页面了解其他选项。

本地运行时，工作目录根目录下需要有 bitrise.yml，也可以选择添加包含敏感输入的 .bitrise.secrets.yml。

常用命令：

# Output the list of available commands
bitrise help

# Start local workflow editor UI
bitrise :workflow-editor

# Validate bitrise.yml
bitrise validate -c {config_path}

# List available workflows
bitrise workflows

# Run a workflow locally
bitrise run {workflow_id}

核心概念

工作区是组织项目及其成员的顶层单元。

项目是 DevOps 流程的容器。项目可以包含 CI 配置（某些工具也称之为 应用），用于基于 Git 仓库运行构建。

步骤是单独的构建任务，可包含输入和输出，以便进行配置并与其他步骤交互。可在步骤库中查找步骤。

步骤包是可重复使用的步骤集合，可包含在多个工作流中以减少重复。

工作流是在运行器机器上按顺序执行的一系列步骤。触发工作流会启动一个构建，并生成日志，还可选择生成可下载文件（构建产物）和／或测试结果。

构建会在适用于某个技术栈（特定版本的操作系统和其他软件工具的组合）的虚拟机上运行，并使用指定的机器类型（用于描述所需硬件资源）。可用的机器类型取决于所选技术栈。使用 bitrise:list_available_stacks 工具或 /available-stacks API 端点获取可用选项。

流水线支持通过依赖关系、并行或顺序执行、分片和文件共享，将工作流组合成复杂流程。

容器（执行容器和服务容器）支持步骤和步骤包在隔离的 Docker 环境中运行，或与后台 Docker 服务一起运行。仅限 Linux，不支持 macOS 技术栈。

环境变量（简称 env）是在不同层级定义的配置变量，并作为输入传递给组件。请参阅此页面，了解构建期间可用的内置 env。

密钥是具有受保护值的 env：它们经过加密存储，并会在构建日志中脱敏。

这些组件通过存储在 Git 仓库中的 bitrise.yml 文件或 Bitrise 网站进行配置。

创建项目

前提条件

源代码需要作为 git 仓库在线提供。可以通过服务用户或 GitHub App 配置仓库访问权限。用户需要先通过 UI 连接提供商。

工作流

确保将过程中出现的任何错误告知用户，不要让用户误以为一切正常，因为关键功能可能无法正常运行。

请使用以下清单：

• 确定源代码仓库
• 确定要添加项目的工作区
• 选择默认分支，并确认该分支存在于远程仓库中。
• 注册应用
• 如果仓库是私有的，注册 SSH 密钥
• 完成应用设置
• 更新 bitrise.yml。先验证文件是否有效。

使用 bitrise:register_app 工具或 /apps/register API 端点注册应用。除非另有说明，否则请将项目设为私有。

可以使用 bitrise:register_ssh_key 工具或 /apps/{app-slug}/register-ssh-key API 端点注册 SSH 密钥。使用上一步获取的 app_slug。

使用 bitrise:finish_bitrise_app 工具或 /apps/{app-slug}/finish API 端点完成应用设置。指定项目类型（默认为 other）以及用于运行构建的堆栈。

更新 bitrise.yml：如果 bitrise.yml 存储在 Bitrise 上，请上传其内容（这是新建应用的默认设置，可使用 /apps/{app-slug}/bitrise.yml/config API 请求检查现有应用）。否则，可以跳过此步骤，因为 bitrise.yml 由源代码仓库进行版本控制。

此处提供了详细文档。

通过 CLI 以交互方式添加项目

如果用户愿意，可以使用 bitrise-add-new-project 工具。这需要 Bitrise 帐户和已检出的 git 仓库。

使用 bitrise.yml

默认情况下，bitrise.yml 存储在 Bitrise 服务器上，不会从源代码仓库读取。也可以切换为将其存储在仓库中，以便进行版本控制、审查等。可以通过 /apps/{app-slug}/bitrise.yml/config API 端点完成此操作。

最佳实践

• 始终先进行规划：通过工作流设计高级流程，然后将其拆分为各个步骤。
• 为流水线、工作流、步骤包和其他资源使用清晰明确的名称。
• 使用 Secret 环境变量存储 API 密钥、令牌、密码和证书口令。使用常规环境变量存储应用名称、Bundle ID、版本号和功能标志。
• 对于云构建，将机密信息存储在 Bitrise Web UI 中
• 绝不要提交 .bitrise.secrets.yml。

结构

JSON 架构请参阅 Schemastore，完整参考请参阅此页面。

• format_version 是必填字段，用于描述配置架构版本（使用 "25" 以支持最新功能）
• default_step_lib_source 也是必填项，用于说明除非另有指定，否则应从何处加载步骤。请使用 https://github.com/bitrise-io/bitrise-steplib.git 作为值。
• containers 定义可供步骤和步骤包使用的 Docker 执行容器及服务容器（仅限 Linux）
• step_bundles、workflows 和 pipelines 列出上述实体（以 ID 为键，格式为映射）
• app 可用于定义应用级环境变量：

  app:
    envs:
      - PROJECT_NAME: MyApp
      - BUNDLE_ID: com.example.myapp
      - VERSION: 1.0.0
  

• 运行 Bitrise 构建需要 meta 块：

  meta:
    bitrise.io:
      stack: linux-docker-android-22.04
  

构建工作流

工作流包含一个步骤列表，可带有可选配置和条件。

• 最常见的顺序是 get sources -> build -> test -> publish or deploy。
• 要从代码库获取源代码，请使用 activate-ssh-key 和 git-clone 步骤启动工作流。
• 某些内置步骤会自动报告测试结果。对于其他工具，需要使用 custom-test-results-export 转换结果，并使用 deploy-to-bitrise-io 将其上传到 Bitrise 以进行报告。详情请参阅此处。
• 可以在不同构建之间缓存依赖项，以提升性能。常见的包管理器都有专用的缓存步骤，其他包管理器则需要手动配置。详情请参阅此处。

示例：

format_version: "25"
meta:
  bitrise.io:
    stack: linux-docker-android-22.04
workflows:
  ci:
    steps:
    - activate-ssh-key@4:
        run_if: '{{getenv "SSH_RSA_PRIVATE_KEY" | ne ""}}'
    - git-clone@8: {}
    - restore-cache@2:
        inputs:
        - key: cache-key-{{ .Branch }}
    - android-unit-test@1:
        inputs:
        - project_location: $PROJECT_LOCATION
        - variant: $VARIANT
    - android-build-for-ui-testing@0:
        inputs:
        - variant: $VARIANT
        - module: $MODULE
    - virtual-device-testing-for-android@1:
        inputs:
        - test_type: instrumentation
    - android-lint@0:
        inputs:
        - variant: "$VARIANT"
    - android-build@1:
        inputs:
        - project_location: "$PROJECT_LOCATION"
        - module: "$MODULE"
        - variant: "$VARIANT"
    - deploy-to-bitrise-io@2: {}
    - slack@3:
        inputs:
        - channel: "#build-notifications"
        - webhook_url: "$SLACK_WEBHOOK"
    - save-cache@1:
        inputs:
        - key: cache-key-{{ .Branch }}
    triggers:
      push:
      - branch: '*'
      pull_request:
      - target_branch: 'main'
      - comment: 
          regex: '.*trigger (b|B)itrise.*'

使用步骤

• 优先使用官方步骤。若某项操作没有专用步骤，请使用 script：

  - script@1:
      title: Print build info
      inputs:
      - content: |
          echo "Building branch: $BITRISE_GIT_BRANCH"
  

• 使用 bitrise:step_search 工具或 /search-steps 端点查找步骤。
• 指定步骤时，请锁定主版本（例如 git-clone@8），这样既能防止破坏性变更，也能获得错误修复。使用步骤搜索工具进行确认。
• 使用 bitrise:step_inputs 工具或 /step-inputs 端点获取步骤输入信息。

条件执行步骤

使用 run_if 根据条件控制步骤的执行：

- slack@3:
    run_if: .IsBuildFailed
    inputs:
      - webhook_url: $SLACK_WEBHOOK_URL
      - text: "Build failed on ${BITRISE_GIT_BRANCH}"

可用表达式：.IsBuildFailed、.IsCI、.IsPR、{{getenv "VAR" | ne ""}}

步骤包

当同一组步骤序列出现在多个工作流中时，可将它们提取为步骤包，以优化工作流。步骤包可使用 bundle:: 前缀进行引用，并且可以像步骤一样配置输入和输出。步骤包可以嵌套。

示例：

step_bundles:
  install_deps:    
    inputs:
    - cache_key: "npm-cache-{{ checksum "package-lock.json" }}"
    - npm_command: install
    steps:    
    - restore-cache@2:
        inputs:
        - key: $cache_key
    - npm@1:
        inputs: 
        - command: $npm_command
workflows:
  ci:
    steps:
    - git-clone@8: {}
    - bundle::install_deps:        
        inputs:
        - cache_key: "npm-cache"
    - deploy-to-bitrise-io@2: {} 

创建新工作流时，始终优先使用步骤包，而不是已弃用的 before_run 或 after_run 结构；现有工作流中的这些结构则保持不变。

Docker 容器

Docker 容器可让步骤和步骤包在隔离的 Docker 环境中运行，或与后台服务一起运行。仅支持 Linux，不支持 macOS 栈。

容器在顶层的 containers 键下定义，并由各个步骤或步骤包引用。

执行容器

使用 type: execution 在特定 Docker 镜像中运行步骤：

containers:
  node-21:
    type: execution
    image: node:21.6
    ports:
      - 3000:3000
    envs:
      - NODE_ENV: ci
    credentials:
      username: $DOCKER_USERNAME
      password: $DOCKER_PASSWORD

在步骤中使用 execution_container 引用（可使用字符串简写，也可使用对象形式设置选项）：

workflows:
  ci:
    steps:
      - script@1:
          execution_container: node-21          # string shorthand: reuse existing instance
          inputs:
            - content: node --version
      - script@1:
          execution_container:
            node-21:
              recreate: true                    # object form: discard and start fresh
          inputs:
            - content: node --version

主要行为：

• 就近优先继承：步骤首先使用自身的 execution_container 定义，其次使用父级步骤包的定义，再其次使用祖父级的定义。每个步骤仅激活一个执行容器。
• 使用处覆盖：引用步骤包时，在调用处设置 execution_container 会覆盖步骤包定义内部指定的容器。覆盖优先级为：步骤级 > 步骤包调用处 > 步骤包定义。

  step_bundles:
    run-tests:
      execution_container: ruby   # bundle definition default
      steps:
      - script@1:
          inputs:
          - content: bundle exec rspec
  workflows:
    ci:
      steps:
      - bundle::run-tests:
          execution_container: ruby-3-3   # call-site overrides the definition
  

• 文件共享：/bitrise、/root/.bitrise 和 /tmp 在所有容器与主机之间共享。默认工作目录为 /bitrise/src。
• 容器复用：默认情况下，容器会在多个步骤间复用；使用带有 recreate: true 的对象形式可强制创建新实例（参见上方示例）。

服务容器

使用 type: service，在运行 Steps 的同时启动后台 Docker 服务（数据库、HTTP 服务器等）：

containers:
  postgres:
    type: service
    image: postgres:16
    ports:
      - 5432:5432
    envs:
      - POSTGRES_PASSWORD: $POSTGRES_PASSWORD
    credentials:
      username: $DOCKER_USERNAME
      password: $DOCKER_PASSWORD
      server: us-central1-docker.pkg.dev
    options: >-
      --health-cmd pg_isready
      --health-interval 10s

在 Step 中通过 service_containers 引用（混合使用字符串简写和对象形式）：

workflows:
  ci:
    steps:
      - script@1:
          service_containers:
            - postgres:
                recreate: true    # object form: discard and start fresh
            - redis               # string shorthand: reuse existing instance

主要行为：

• 累加继承：服务容器会从所有祖先 Step bundle 层级累加——不同于执行容器，它们不会被最近的父级覆盖。
• 使用端覆盖：在 bundle 调用处设置 service_containers，会覆盖 bundle 定义中指定的服务容器。
• 网络：所有服务容器共享一个 bitrise Docker 网络。
  • 当 Step 使用执行容器时：通过容器 ID 作为主机名访问服务（例如，http://postgres:5432）。
  • 当 Step 直接在主机上运行时：通过 localhost 访问服务（例如，http://localhost:5432）。

凭据

将 Docker registry 凭据存储为 Secrets，并在 credentials 块中引用它们（username、password，以及非 Docker Hub registry 可选的 server）。

不支持的选项

options 字段不支持 Docker 选项 --network、--volume（-v）和 --entrypoint。

旧版 with: 组

较早的语法在步骤列表中使用 with: 块，其中包含 container（字符串）和 services（字符串列表）属性。请勿在新配置中使用此语法——它不能与基于步骤的 execution_container/service_containers 语法在同一个 bitrise.yml 中混用。

构建自定义 Docker 镜像

使用 docker-build-push Step 在工作流期间构建并推送自定义镜像，随后可在构建中将其作为容器镜像引用。

构建流水线

设计包含依赖关系、并行处理、分片和制品共享的多工作流流程。完整详情请参阅 pipelines.md。

创建新流水线时，始终优先使用 depends_on 声明显式依赖关系。仅在编辑已有阶段的现有流水线时使用 stages。

触发器

工作流和流水线可以指定源代码仓库事件的条件，以决定是否启动构建。

每个流水线或工作流都可以设置触发器。可以添加多个触发器，每个触发器可以指定多个条件。所有包含匹配触发器项的流水线/工作流都会启动。

示例：

workflows:
  workflow-tests:
    triggers:
      push:
      # Exact match
      - branch: "release" 
pipelines:
  pipeline-build:
    workflows: {}
    triggers:
      push: 
      # Using a wildcard
      - branch: "*"
      # Multiple conditions
      - branch: release
        changed_files: path/to/library-a/.*
      tag:
      # Regex
      - name:
          regex: '^\d\.\d\.\d$'

旧版格式

顶层 trigger_map 标签包含一个有序的条目列表。对于传入事件，第一个匹配的条目会启动具有指定流水线/工作流的构建。 创建新的 bitrise.yml 文件时，始终优先使用新格式；仅在已有 trigger_map 时使用它。

模块化 YAML

企业版计划支持将 bitrise.yml 拆分为多个文件，以反映组织或代码结构，并减少冲突。详情请参阅这里。

示例：

format_version: "25"
include:
  - _workflows/shared.yml
  - _workflows/ios.yml
  - _workflows/android.yml

验证结果

使用此工作流：

1. 验证 YML 文件。对于大型文件，如果已安装 CLI，请使用 CLI；也可以将文件流式传输到 cURL，以使用 API。

• bitrise validate -c bitrise.yml
• bitrise:validate_bitrise_yml MCP 工具
• /validate-bitrise-yml API 端点

2. 如果验证失败：
   • 仔细检查错误消息
   • 修复问题
   • 再次运行验证
3. 仅在验证通过后继续
4. 尽可能在本地测试：bitrise run {workflow_id}

构建故障排查

1. 检查构建日志。
2. 找出失败的步骤（可能不止一个），并在其输出中查找错误。
3. 确定失败是由配置问题（无效的 stack、顺序错误等）还是源代码问题（测试、lint 等）导致的。
4. 如果是配置问题：不要移除失败的步骤。确认使用了正确的步骤，并修复其配置。必要时提出澄清问题。通常，不要编辑或移除配置中无关的部分。

有用链接

• Bitrise 文档：https://docs.bitrise.io/
• Step Library：https://github.com/bitrise-steplib 这里的每个步骤都是一个代码仓库。
• Bitrise CLI（GitHub）：https://github.com/bitrise-io/bitrise
• bitrise.yml 参考：https://docs.bitrise.io/en/bitrise-ci/references/configuration-yaml-reference.html
• Stacks 文档：https://bitrise.io/stacks