using-bitrise-ci

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Using Bitrise CI

使用Bitrise CI

Contents

目录

  • Tools (Authentication, MCP, API, CLI)
  • Core concepts
  • Creating projects
  • Working with bitrise.yml (Structure, Components)
  • Troubleshooting builds
  • 工具(身份验证、MCP、API、CLI)
  • 核心概念
  • 创建项目
  • 处理bitrise.yml(结构、组件)
  • 排查构建问题

Automated access

自动化访问

Authentication

身份验证

An access token is required to interact with Bitrise in automated ways (API, MCP etc.). Users can create a personal or workspace access token. It should be stored securely.
通过自动化方式(如API、MCP等)与Bitrise交互时需要访问令牌。用户可以创建个人访问令牌工作区访问令牌,并应妥善安全存储。

MCP server

MCP服务器

The Bitrise MCP server is available online at https://github.com/bitrise-io/bitrise-mcp, or it can be run locally. It requires authentication with a token using the
Authorization: Bearer {token}
header. When the MCP server is available, prefer it to the API or other tools.
Bitrise MCP服务器可通过在线地址https://github.com/bitrise-io/bitrise-mcp访问,也可本地运行。它需要通过`Authorization: Bearer {token}`头携带令牌进行身份验证。当MCP服务器可用时,优先使用它而非API或其他工具。

API

API

The Bitrise REST API allows managing various Bitrise resources. The detailed reference is available here. The API requires authentication with a PAT with the
Authorization: {PAT}
header (without
Bearer
).
Bitrise REST API可用于管理各类Bitrise资源,详细参考文档可查看此处。API需要使用PAT进行身份验证,请求头格式为
Authorization: {PAT}
(无需添加
Bearer
前缀)。

CLI

CLI

Bitrise CLI is useful when working on a local environment. It doesn't interact with Bitrise resources, but helps with editing and validating
bitrise.yml
, and allows running workflows locally. It supports Mac and Linux.
To install, use
brew install bitrise
or check the Releases page for other options.
Local runs expect
bitrise.yml
at the root of the working directory, with an optional
.bitrise.secrets.yml
containing sensitive inputs.
Common commands:
bash
undefined
Bitrise CLI适用于本地环境操作,它不与Bitrise云端资源交互,但可帮助编辑和验证
bitrise.yml
,并支持本地运行工作流。它兼容Mac和Linux系统。
安装方式:使用
brew install bitrise
,或查看发布页面获取其他安装选项。
本地运行时,需在工作目录根目录放置
bitrise.yml
,可选搭配包含敏感输入信息的
.bitrise.secrets.yml
文件。
常用命令:
bash
undefined

Output the list of available commands

输出可用命令列表

bitrise help
bitrise help

Start local workflow editor UI

启动本地工作流编辑器UI

bitrise :workflow-editor
bitrise :workflow-editor

Validate bitrise.yml

验证bitrise.yml

bitrise validate -c {config_path}
bitrise validate -c {config_path}

List available workflows

列出可用工作流

bitrise workflows
bitrise workflows

Run a workflow locally

本地运行指定工作流

bitrise run {workflow_id}
undefined
bitrise run {workflow_id}
undefined

Core concepts

核心概念

Workspaces are the top-level units of organizing projects and their members.
A project is a container for the DevOps process. Projects can contain CI configuration (also called apps by some tools) to run builds based on a git repository.
Steps are individual build tasks that can have inputs and outputs to allow configuration and interacting with other steps. Steps can be found in the Step Library.
Step bundles are reusable collections of steps that can be included in multiple workflows to reduce duplication.
Workflows are sequences of steps executed in order on a runner machine. Triggering a workflow starts a build, which produces a log, and optionally downloadable files (artifacts) and/or test results.
Builds run on a virtual machine for a stack (a combination of specific versions of an OS and additional software tools), on the specified machine type that describes the hardware resources requested. Available machine types depend on the selected stack. Use the
bitrise:list_available_stacks
tool or the
/available-stacks
API endpoint to get the options.
Pipelines allow creating complex processes from workflows with dependencies, parallel or sequential execution, sharding and sharing files.
Environment variables (envs for short) are configuration variables that can be defined on various levels and are passed to components as inputs. See this page for built-in envs available during builds.
Secrets are envs with protected values: they are stored encrypted, and are redacted in build logs.
These components are configured via the
bitrise.yml
file stored in the git repository or the Bitrise website.
Workspaces是组织项目及其成员的顶级单元。
Project是DevOps流程的容器,项目可包含CI配置(部分工具也称为apps),用于基于Git仓库运行构建。
Steps是独立的构建任务,可包含输入和输出,用于配置和与其他步骤交互。可在Step Library中查找步骤。
Step bundles是可复用的步骤集合,可在多个工作流中引用以减少重复代码。
Workflows是在运行器机器上按顺序执行的步骤序列。触发工作流会启动一个build,构建会生成日志,可选生成可下载文件(artifacts)和/或测试结果。
构建在对应stack(特定版本操作系统与附加软件工具的组合)的虚拟机上运行,运行时需指定machine type以描述所需硬件资源。可用的机器类型取决于所选stack,可使用
bitrise:list_available_stacks
工具或
/available-stacks
API端点获取可选配置。
Pipelines允许通过依赖关系、并行或顺序执行、分片和文件共享创建复杂流程。
Environment variables(简称envs)是可在不同层级定义的配置变量,会作为输入传递给各个组件。构建过程中可用的内置envs可查看此页面
Secrets是值受保护的envs:它们以加密方式存储,且在构建日志中会被脱敏处理。
这些组件通过存储在Git仓库或Bitrise网站上的
bitrise.yml
文件进行配置。

Creating projects

创建项目

Prerequisites

前提条件

The source needs to be available as a git repository online. Repository access can be configured via service users or a GitHub App. The user needs to connect with a provider via the UI first.
源代码需托管为在线Git仓库。可通过服务用户或GitHub App配置仓库访问权限。用户需先通过UI连接对应代码托管提供商。

Workflow

流程

Make sure to surface any errors that occur during the process, don't leave the user with the impression that everything went OK, as critical functionality might be broken.
Use the following checklist:
  • Determine the source repository
  • Determine the workspace to add the project
  • Select a default branch and verify that it exists in the remote repository.
  • Register the app
  • If the repository is private, register SSH keys
  • Finish the app setup
  • Update bitrise.yml. Verify that it is valid first.
Register the app using the
bitrise:register_app
tool or the
/apps/register
API endpoint. Unless instructed otherwise, create the project as private.
Registering SSH keys can be done via the
bitrise:register_ssh_key
tool or the
/apps/{app-slug}/register-ssh-key
API endpoint. Use the
app_slug
received from the previous step.
Finish the app setup with the
bitrise:finish_bitrise_app
tool or the
/apps/{app-slug}/finish
API endpoint. Specify a project type (default is
other
) and a stack to run builds on.
Updating bitrise.yml: Upload the contents of bitrise.yml if it is stored on Bitrise (This is the default for newly created apps,
/apps/{app-slug}/bitrise.yml/config
API request can be used to check for existing apps). Otherwise this step can be skipped as bitrise.yml is version controlled in the source repo.
Detailed documentation is available here.
过程中需及时反馈出现的任何错误,不要让用户误以为一切正常,否则可能导致关键功能失效。
使用以下检查清单:
  • 确定源代码仓库
  • 确定要添加项目的工作区
  • 选择默认分支并验证其在远程仓库中存在
  • 注册应用
  • 若仓库为私有,注册SSH密钥
  • 完成应用设置
  • 更新bitrise.yml,先验证其有效性
注册应用可使用
bitrise:register_app
工具或
/apps/register
API端点。除非另有说明,否则将项目创建为私有。
注册SSH密钥可通过
bitrise:register_ssh_key
工具或
/apps/{app-slug}/register-ssh-key
API端点完成,需使用上一步获取的
app_slug
完成应用设置可使用
bitrise:finish_bitrise_app
工具或
/apps/{app-slug}/finish
API端点,需指定项目类型(默认为
other
)和运行构建的stack。
更新bitrise.yml:若配置存储在Bitrise云端(新创建应用的默认方式),则上传bitrise.yml内容(可使用
/apps/{app-slug}/bitrise.yml/config
API请求检查现有应用的配置情况)。若配置已在源代码仓库中进行版本控制,则可跳过此步骤。
详细文档可查看此处

Adding a project interactively from CLI

通过CLI交互式添加项目

If the user prefers so, the bitrise-add-new-project tool can be used. This requires a Bitrise account and a checked out git repository.
若用户偏好此方式,可使用bitrise-add-new-project工具。此方式需要Bitrise账户和已克隆的Git仓库。

Working with bitrise.yml

处理bitrise.yml

By default, bitrise.yml is stored on Bitrise servers and not read from the source repository. It is possible to switch to storing it in the repository, allowing version control, reviews etc. This can be done via the
/apps/{app-slug}/bitrise.yml/config
API endpoint.
默认情况下,bitrise.yml存储在Bitrise服务器上,而非从源代码仓库读取。也可切换为存储在仓库中,以支持版本控制和代码评审等功能,可通过
/apps/{app-slug}/bitrise.yml/config
API端点完成设置。

Best Practices

最佳实践

  • Always plan first: design the high-level process via workflows, then break them down into steps.
  • Use clear, descriptive names for pipelines, workflows, step bundles and other resources.
  • Use Secret env vars for API keys, tokens, passwords, certificate passphrases. Use regular env vars for app names, bundle IDs, version numbers, feature flags.
  • Store secrets in Bitrise web UI for cloud builds
  • NEVER commit
    .bitrise.secrets.yml
    .
  • 始终先规划:通过工作流设计高层级流程,再将其拆分为步骤
  • 为pipelines、workflows、step bundles及其他资源使用清晰、具有描述性的名称
  • 使用Secret env存储API密钥、令牌、密码、证书密码等敏感信息;使用普通env存储应用名称、Bundle ID、版本号、功能标志等
  • 云端构建的secrets存储在Bitrise网页UI中
  • 绝对不要提交
    .bitrise.secrets.yml
    文件

Structure

结构

See Schemastore for the JSON schema or this page a complete reference.
  • format_version
    is a required field describing the configuration schema version (use
    "25"
    for latest features)
  • default_step_lib_source
    is also required, it describes where steps should be loaded from unless specified otherwise. Use https://github.com/bitrise-io/bitrise-steplib.git as value.
  • step_bundles
    ,
    workflows
    and
    pipelines
    list the entities described above (formatted as a map with ID as key)
  • app
    can be used to define app-level envs:
    yaml
    app:
      envs:
        - PROJECT_NAME: MyApp
        - BUNDLE_ID: com.example.myapp
        - VERSION: 1.0.0
  • meta
    block is required for running builds on Bitrise:
    yaml
    meta:
      bitrise.io:
        stack: linux-docker-android-22.04
可查看Schemastore获取JSON schema,或查看此页面获取完整参考文档。
  • format_version
    是必填字段,描述配置schema版本(使用
    "25"
    以支持最新功能)
  • default_step_lib_source
    也是必填字段,描述步骤的默认加载源,除非单独指定。值使用https://github.com/bitrise-io/bitrise-steplib.git
  • step_bundles
    workflows
    pipelines
    字段列出上述实体(以ID为键的映射格式)
  • app
    字段可用于定义应用级别的envs:
    yaml
    app:
      envs:
        - PROJECT_NAME: MyApp
        - BUNDLE_ID: com.example.myapp
        - VERSION: 1.0.0
  • meta
    块是在Bitrise上运行构建的必填项:
    yaml
    meta:
      bitrise.io:
        stack: linux-docker-android-22.04

Building Workflows

构建Workflows

Workflows contain a list of steps with optional configuration and conditions.
  • The most common sequence is
    get sources
    ->
    build
    ->
    test
    ->
    publish or deploy
    .
  • To get the sources from a repository, start a workflow with the
    activate-ssh-key
    and
    git-clone
    steps.
  • Test results are automatically reported from certain built-in steps. For other tools, the
    custom-test-results-export
    is needed to convert the results, and
    deploy-to-bitrise-io
    to upload them to Bitrise for reporting. Details here.
  • Dependencies can be cached between builds for better performance. Popular package managers have dedicated caching steps, others require manual configuration. Details here.
Example:
yaml
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.*'
Workflows包含带可选配置和条件的步骤列表。
  • 最常见的流程序列是
    获取源代码
    ->
    构建
    ->
    测试
    ->
    发布或部署
  • 若要从仓库获取源代码,工作流需以
    activate-ssh-key
    git-clone
    步骤开头
  • 部分内置步骤会自动上报测试结果。对于其他工具,需使用
    custom-test-results-export
    转换结果,并使用
    deploy-to-bitrise-io
    上传至Bitrise以完成上报,详细信息可查看此处
  • 可在构建之间缓存依赖以提升性能,主流包管理器有专用的缓存步骤,其他工具需手动配置,详细信息可查看此处
示例:
yaml
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.*'

Using steps

使用Steps

  • Prefer official steps to other sources. When no dedicated step is available for an action, use
    script
    :
    yaml
    - script@1:
        title: Print build info
        inputs:
        - content: |
            echo "Building branch: $BITRISE_GIT_BRANCH"
  • Use the
    bitrise:step_search
    tool or the
    /search-steps
    endpoint to find steps.
  • When specifying steps, lock to the major version (e.g.
    git-clone@8
    ), this guards against breaking changes but allows bug fixes. Use the step search tools to verify.
  • Use the
    bitrise:step_inputs
    tool or the
    /step-inputs
    endpoint to get data about the step inputs.
  • 优先使用官方步骤,若无对应专用步骤,可使用
    script
    步骤:
    yaml
    - script@1:
        title: Print build info
        inputs:
        - content: |
            echo "Building branch: $BITRISE_GIT_BRANCH"
  • 可使用
    bitrise:step_search
    工具或
    /search-steps
    端点查找步骤
  • 指定步骤时,锁定主版本(例如
    git-clone@8
    ),这可避免破坏性变更,同时允许接收bug修复。可通过步骤搜索工具验证版本
  • 可使用
    bitrise:step_inputs
    工具或
    /step-inputs
    端点获取步骤输入的相关信息

Conditional Step Execution

条件性步骤执行

Use
run_if
to control Step execution based on conditions:
yaml
- slack@3:
    run_if: .IsBuildFailed
    inputs:
      - webhook_url: $SLACK_WEBHOOK_URL
      - text: "Build failed on ${BITRISE_GIT_BRANCH}"
Available expressions:
.IsBuildFailed
,
.IsCI
,
.IsPR
,
{{getenv "VAR" | ne ""}}
使用
run_if
根据条件控制步骤执行:
yaml
- slack@3:
    run_if: .IsBuildFailed
    inputs:
      - webhook_url: $SLACK_WEBHOOK_URL
      - text: "Build failed on ${BITRISE_GIT_BRANCH}"
可用表达式:
.IsBuildFailed
,
.IsCI
,
.IsPR
,
{{getenv "VAR" | ne ""}}

Step bundles

Step bundles

When the same sequence of steps appears in multiple workflows, extract them into a step bundle to optimize the workflows. Step bundles can be referenced with the
bundle::
prefix, and can be configured with inputs/outputs like steps. It is possible to nest step bundles.
Example:
yaml
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: {} 
ALWAYS prefer step bundles to the obsolete
before_run
or
after_run
constructs when creating new workflows, leave them in existing ones.
当相同的步骤序列出现在多个工作流中时,可将其提取为step bundle以优化工作流。Step bundle可通过
bundle::
前缀引用,且可像步骤一样配置输入/输出。Step bundle支持嵌套。
示例:
yaml
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: {} 
创建新工作流时,始终优先使用step bundles而非已废弃的
before_run
after_run
语法;现有工作流中的该语法可保留。

Building pipelines

构建Pipelines

Design multi-workflow processes with dependencies, parallelism, sharding and artifact sharing. See pipelines.md for full details.
ALWAYS prefer using explicit dependencies with
depends_on
when creating new pipelines. Use stages only when editing an existing pipeline that already contains them.
通过依赖关系、并行执行、分片和工件共享设计多工作流流程,详细信息可查看pipelines.md
创建新pipeline时,始终优先使用
depends_on
定义显式依赖关系;仅在编辑已包含stages的现有pipeline时才使用stages。

Triggers

触发器

Workflows and pipelines can specify conditions for events from the source repository that should start builds.
Triggers can be set on each pipeline or workflow. Multiple triggers can be added, and each can specify multiple conditions. All pipelines/workflows that have a matching trigger item will be started.
Examples:
yaml
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$'
Workflows和pipelines可定义源代码仓库事件触发构建的条件。
Triggers可在每个pipeline或workflow上设置。可添加多个触发器,每个触发器可指定多个条件。所有匹配触发器规则的pipelines/workflows都会被启动。
示例:
yaml
workflows:
  workflow-tests:
    triggers:
      push:
      # 精确匹配
      - branch: "release" 
pipelines:
  pipeline-build:
    workflows: {}
    triggers:
      push: 
      # 使用通配符
      - branch: "*"
      # 多条件
      - branch: release
        changed_files: path/to/library-a/.*
      tag:
      # 正则匹配
      - name:
          regex: '^\d\.\d\.\d$'

Legacy format

旧版格式

The top-level
trigger_map
tag contains an ordered list of items. For an incoming event, the first matching item will start a build with the specified pipeline/workflow. ALWAYS prefer the new format when creating a new bitrise.yml file, only use
trigger_map
when already present.
顶层
trigger_map
标签包含有序的触发器列表。对于传入事件,第一个匹配的触发器会启动指定pipeline/workflow的构建。 创建新的bitrise.yml文件时,始终优先使用新版格式;仅在已有
trigger_map
的文件中才使用该旧格式。

Modular YAML

模块化YAML

On enterprise plans, it is possible to split
bitrise.yml
into multiple files to reflect organizational or code structure, and to reduce conflicts. See details here.
Example:
yaml
format_version: "25"
include:
  - _workflows/shared.yml
  - _workflows/ios.yml
  - _workflows/android.yml
在企业版计划中,可将
bitrise.yml
拆分为多个文件以匹配组织或代码结构,并减少冲突,详细信息可查看此处
示例:
yaml
format_version: "25"
include:
  - _workflows/shared.yml
  - _workflows/ios.yml
  - _workflows/android.yml

Verifying results

验证结果

Use this workflow:
  1. Validate the YML file(s). For large files, use the CLI if installed, or the API by streaming the file into cURL.
  • bitrise validate -c bitrise.yml
  • bitrise:validate_bitrise_yml
    MCP tool
  • /validate-bitrise-yml
    API endpoint
  1. If validation fails:
    • Review error messages carefully
    • Fix the issues
    • Run validation again
  2. Only proceed when validation passes
  3. Test locally if possible:
    bitrise run {workflow_id}
使用以下流程:
  1. 验证YML文件(若文件较大,已安装CLI则使用CLI验证,否则通过cURL将文件流式传输至API验证)
  • bitrise validate -c bitrise.yml
  • bitrise:validate_bitrise_yml
    MCP工具
  • /validate-bitrise-yml
    API端点
  1. 若验证失败:
    • 仔细查看错误信息
    • 修复问题
    • 重新运行验证
  2. 仅在验证通过后再继续后续操作
  3. 若可能,本地测试:
    bitrise run {workflow_id}

Troubleshooting builds

排查构建问题

  1. Check the build logs.
  2. Identify failing steps (there can be multiple) and find errors in their output.
  3. Determine whether the failure was because of a problem with the configuration (invalid stack, incorrect order etc.) or the source (tests, linting etc.)
  4. If it's a configuration issue: don't remove failing steps. Verify that the right step is used and fix its configuration. Ask clarifying questions if necessary. In general, do not edit or remove unrelated parts of the configuration.
  1. 查看构建日志
  2. 识别失败的步骤(可能有多个)并在其输出中查找错误
  3. 判断失败原因是配置问题(无效stack、步骤顺序错误等)还是源代码问题(测试失败、代码检查不通过等)
  4. 若为配置问题:不要删除失败的步骤,验证是否使用了正确的步骤并修复其配置。必要时询问用户以明确信息。一般情况下,不要编辑或删除配置中无关的部分。

Useful Links

有用链接