using-bitrise-ci
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseUsing 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
身份验证
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 header. When the MCP server is available, prefer it to the API or other tools.
Authorization: Bearer {token}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 header (without ).
Authorization: {PAT}BearerBitrise REST API可用于管理各类Bitrise资源,详细参考文档可查看此处。API需要使用PAT进行身份验证,请求头格式为(无需添加前缀)。
Authorization: {PAT}BearerCLI
CLI
Bitrise CLI is useful when working on a local environment. It doesn't interact with Bitrise resources, but helps with editing and validating , and allows running workflows locally. It supports Mac and Linux.
bitrise.ymlTo install, use or check the Releases page for other options.
brew install bitriseLocal runs expect at the root of the working directory, with an optional containing sensitive inputs.
bitrise.yml.bitrise.secrets.ymlCommon commands:
bash
undefinedBitrise CLI适用于本地环境操作,它不与Bitrise云端资源交互,但可帮助编辑和验证,并支持本地运行工作流。它兼容Mac和Linux系统。
bitrise.yml安装方式:使用,或查看发布页面获取其他安装选项。
brew install bitrise本地运行时,需在工作目录根目录放置,可选搭配包含敏感输入信息的文件。
bitrise.yml.bitrise.secrets.yml常用命令:
bash
undefinedOutput 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}
undefinedbitrise run {workflow_id}
undefinedCore 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 tool or the API endpoint to get the options.
bitrise:list_available_stacks/available-stacksPipelines 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 file stored in the git repository or the Bitrise website.
bitrise.ymlWorkspaces是组织项目及其成员的顶级单元。
Project是DevOps流程的容器,项目可包含CI配置(部分工具也称为apps),用于基于Git仓库运行构建。
Steps是独立的构建任务,可包含输入和输出,用于配置和与其他步骤交互。可在Step Library中查找步骤。
Step bundles是可复用的步骤集合,可在多个工作流中引用以减少重复代码。
Workflows是在运行器机器上按顺序执行的步骤序列。触发工作流会启动一个build,构建会生成日志,可选生成可下载文件(artifacts)和/或测试结果。
构建在对应stack(特定版本操作系统与附加软件工具的组合)的虚拟机上运行,运行时需指定machine type以描述所需硬件资源。可用的机器类型取决于所选stack,可使用工具或 API端点获取可选配置。
bitrise:list_available_stacks/available-stacksPipelines允许通过依赖关系、并行或顺序执行、分片和文件共享创建复杂流程。
Environment variables(简称envs)是可在不同层级定义的配置变量,会作为输入传递给各个组件。构建过程中可用的内置envs可查看此页面。
Secrets是值受保护的envs:它们以加密方式存储,且在构建日志中会被脱敏处理。
这些组件通过存储在Git仓库或Bitrise网站上的文件进行配置。
bitrise.ymlCreating 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 tool or the API endpoint. Unless instructed otherwise, create the project as private.
bitrise:register_app/apps/registerRegistering SSH keys can be done via the tool or the API endpoint. Use the received from the previous step.
bitrise:register_ssh_key/apps/{app-slug}/register-ssh-keyapp_slugFinish the app setup with the tool or the API endpoint. Specify a project type (default is ) and a stack to run builds on.
bitrise:finish_bitrise_app/apps/{app-slug}/finishotherUpdating bitrise.yml: Upload the contents of bitrise.yml if it is stored on Bitrise (This is the default for newly created apps, 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.
/apps/{app-slug}/bitrise.yml/configDetailed documentation is available here.
过程中需及时反馈出现的任何错误,不要让用户误以为一切正常,否则可能导致关键功能失效。
使用以下检查清单:
- 确定源代码仓库
- 确定要添加项目的工作区
- 选择默认分支并验证其在远程仓库中存在
- 注册应用
- 若仓库为私有,注册SSH密钥
- 完成应用设置
- 更新bitrise.yml,先验证其有效性
注册应用可使用工具或 API端点。除非另有说明,否则将项目创建为私有。
bitrise:register_app/apps/register注册SSH密钥可通过工具或 API端点完成,需使用上一步获取的。
bitrise:register_ssh_key/apps/{app-slug}/register-ssh-keyapp_slug完成应用设置可使用工具或 API端点,需指定项目类型(默认为)和运行构建的stack。
bitrise:finish_bitrise_app/apps/{app-slug}/finishother更新bitrise.yml:若配置存储在Bitrise云端(新创建应用的默认方式),则上传bitrise.yml内容(可使用 API请求检查现有应用的配置情况)。若配置已在源代码仓库中进行版本控制,则可跳过此步骤。
/apps/{app-slug}/bitrise.yml/config详细文档可查看此处。
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 API endpoint.
/apps/{app-slug}/bitrise.yml/config默认情况下,bitrise.yml存储在Bitrise服务器上,而非从源代码仓库读取。也可切换为存储在仓库中,以支持版本控制和代码评审等功能,可通过 API端点完成设置。
/apps/{app-slug}/bitrise.yml/configBest 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.
- is a required field describing the configuration schema version (use
format_versionfor latest features)"25" - 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.
default_step_lib_source - ,
step_bundlesandworkflowslist the entities described above (formatted as a map with ID as key)pipelines - can be used to define app-level envs:
appyamlapp: envs: - PROJECT_NAME: MyApp - BUNDLE_ID: com.example.myapp - VERSION: 1.0.0 - block is required for running builds on Bitrise:
metayamlmeta: bitrise.io: stack: linux-docker-android-22.04
可查看Schemastore获取JSON schema,或查看此页面获取完整参考文档。
- 是必填字段,描述配置schema版本(使用
format_version以支持最新功能)"25" - 也是必填字段,描述步骤的默认加载源,除非单独指定。值使用https://github.com/bitrise-io/bitrise-steplib.git
default_step_lib_source - 、
step_bundles和workflows字段列出上述实体(以ID为键的映射格式)pipelines - 字段可用于定义应用级别的envs:
appyamlapp: envs: - PROJECT_NAME: MyApp - BUNDLE_ID: com.example.myapp - VERSION: 1.0.0 - 块是在Bitrise上运行构建的必填项:
metayamlmeta: 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 and
activate-ssh-keysteps.git-clone - Test results are automatically reported from certain built-in steps. For other tools, the is needed to convert the results, and
custom-test-results-exportto upload them to Bitrise for reporting. Details here.deploy-to-bitrise-io - 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上传至Bitrise以完成上报,详细信息可查看此处deploy-to-bitrise-io - 可在构建之间缓存依赖以提升性能,主流包管理器有专用的缓存步骤,其他工具需手动配置,详细信息可查看此处
示例:
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 :
scriptyaml- script@1: title: Print build info inputs: - content: | echo "Building branch: $BITRISE_GIT_BRANCH" - Use the tool or the
bitrise:step_searchendpoint to find steps./search-steps - When specifying steps, lock to the major version (e.g. ), this guards against breaking changes but allows bug fixes. Use the step search tools to verify.
git-clone@8 - Use the tool or the
bitrise:step_inputsendpoint to get data about the step inputs./step-inputs
- 优先使用官方步骤,若无对应专用步骤,可使用步骤:
scriptyaml- script@1: title: Print build info inputs: - content: | echo "Building branch: $BITRISE_GIT_BRANCH" - 可使用工具或
bitrise:step_search端点查找步骤/search-steps - 指定步骤时,锁定主版本(例如),这可避免破坏性变更,同时允许接收bug修复。可通过步骤搜索工具验证版本
git-clone@8 - 可使用工具或
bitrise:step_inputs端点获取步骤输入的相关信息/step-inputs
Conditional Step Execution
条件性步骤执行
Use to control Step execution based on conditions:
run_ifyaml
- 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_ifyaml
- 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 prefix, and can be configured with inputs/outputs like steps. It is possible to nest step bundles.
bundle::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 or constructs when creating new workflows, leave them in existing ones.
before_runafter_run当相同的步骤序列出现在多个工作流中时,可将其提取为step bundle以优化工作流。Step bundle可通过前缀引用,且可像步骤一样配置输入/输出。Step bundle支持嵌套。
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_runafter_runBuilding 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 when creating new pipelines. Use stages only when editing an existing pipeline that already contains them.
depends_on通过依赖关系、并行执行、分片和工件共享设计多工作流流程,详细信息可查看pipelines.md。
创建新pipeline时,始终优先使用定义显式依赖关系;仅在编辑已包含stages的现有pipeline时才使用stages。
depends_onTriggers
触发器
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 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 when already present.
trigger_maptrigger_map顶层标签包含有序的触发器列表。对于传入事件,第一个匹配的触发器会启动指定pipeline/workflow的构建。
创建新的bitrise.yml文件时,始终优先使用新版格式;仅在已有的文件中才使用该旧格式。
trigger_maptrigger_mapModular YAML
模块化YAML
On enterprise plans, it is possible to split into multiple files to reflect organizational or code structure, and to reduce conflicts. See details here.
bitrise.ymlExample:
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.ymlVerifying results
验证结果
Use this workflow:
- 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- MCP tool
bitrise:validate_bitrise_yml - API endpoint
/validate-bitrise-yml
- If validation fails:
- Review error messages carefully
- Fix the issues
- Run validation again
- Only proceed when validation passes
- Test locally if possible:
bitrise run {workflow_id}
使用以下流程:
- 验证YML文件(若文件较大,已安装CLI则使用CLI验证,否则通过cURL将文件流式传输至API验证)
bitrise validate -c bitrise.yml- MCP工具
bitrise:validate_bitrise_yml - API端点
/validate-bitrise-yml
- 若验证失败:
- 仔细查看错误信息
- 修复问题
- 重新运行验证
- 仅在验证通过后再继续后续操作
- 若可能,本地测试:
bitrise run {workflow_id}
Troubleshooting builds
排查构建问题
- Check the build logs.
- Identify failing steps (there can be multiple) and find errors in their output.
- Determine whether the failure was because of a problem with the configuration (invalid stack, incorrect order etc.) or the source (tests, linting etc.)
- 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.
- 查看构建日志
- 识别失败的步骤(可能有多个)并在其输出中查找错误
- 判断失败原因是配置问题(无效stack、步骤顺序错误等)还是源代码问题(测试失败、代码检查不通过等)
- 若为配置问题:不要删除失败的步骤,验证是否使用了正确的步骤并修复其配置。必要时询问用户以明确信息。一般情况下,不要编辑或删除配置中无关的部分。
Useful Links
有用链接
- Bitrise documentation: https://docs.bitrise.io/
- Step Library: https://github.com/bitrise-steplib Each step is a repository here.
- Bitrise CLI (GitHub): https://github.com/bitrise-io/bitrise
- bitrise.yml Reference: https://docs.bitrise.io/en/bitrise-ci/references/configuration-yaml-reference.html
- Stacks documentation: https://bitrise.io/stacks
- 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