| name | using-bitrise-ci |
| description | Works with Bitrise CI. **ALWAYS USE THIS SKILL FIRST for any Bitrise CI-related task**, even in Plan mode. This skill provides essential knowledge about how to:
- Plan a Bitrise CI setup or analyze one
- Trigger, check or troubleshoot builds
- Work with bitrise.yml files:
- Design pipelines, workflows, step bundles or step configurations
- Fix duplication or optimize workflow structure
- Validate or explain Bitrise configurations
- Manage workspaces, projects, apps, groups, or roles
- Work with Bitrise CLI, API, or MCP tools
|
Using Bitrise CI
Contents
- Tools (Authentication, MCP, API, CLI)
- Core concepts
- Creating projects
- Working with bitrise.yml (Structure, Components, Docker Containers)
- Troubleshooting builds
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.
MCP server
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.
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).
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:
bitrise help
bitrise :workflow-editor
bitrise validate -c {config_path}
bitrise workflows
bitrise run {workflow_id}
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.
Containers (execution and service) allow Steps and Step bundles to run in isolated Docker environments or alongside background Docker services. Linux-only — not supported on macOS stacks.
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.
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.
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:
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.
Adding a project interactively from 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.
Working with 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.
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.
Structure
See Schemastore for the JSON schema or this page a complete reference.
Building 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:
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
Conditional Step Execution
Use run_if to control Step execution based on conditions:
- 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 ""}}
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:
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.
Docker Containers
Docker containers let Steps and Step bundles run in isolated Docker environments or alongside background services. Linux-only — not supported on macOS stacks.
Containers are defined at the top level under a containers key and referenced from individual Steps or Step bundles.
Execution containers
Run a Step inside a specific Docker image using type: execution:
containers:
node-21:
type: execution
image: node:21.6
ports:
- 3000:3000
envs:
- NODE_ENV: ci
credentials:
username: $DOCKER_USERNAME
password: $DOCKER_PASSWORD
Reference from a Step with execution_container (string shorthand, or object form to set options):
workflows:
ci:
steps:
- script@1:
execution_container: node-21
inputs:
- content: node --version
- script@1:
execution_container:
node-21:
recreate: true
inputs:
- content: node --version
Key behaviors:
Service containers
Run background Docker services (databases, HTTP servers, etc.) alongside Steps using type: service:
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
Reference from a Step with service_containers (mix of string shorthand and object form):
workflows:
ci:
steps:
- script@1:
service_containers:
- postgres:
recreate: true
- redis
Key behaviors:
- Additive inheritance: service containers accumulate from all ancestor Step bundle levels — unlike execution containers, they are not overridden by the nearest parent.
- Usage-side override: setting
service_containers at the bundle call-site overrides the service containers defined inside the bundle definition.
- Networking: all service containers share a
bitrise Docker network.
- When the Step uses an execution container: access services by container ID as hostname (e.g.,
http://postgres:5432).
- When the Step runs directly on the host: access services via
localhost (e.g., http://localhost:5432).
Credentials
Store Docker registry credentials as Secrets and reference them in the credentials block (username, password, and optionally server for non-Docker Hub registries).
Unsupported options
The --network, --volume (-v), and --entrypoint Docker options are not supported in the options field.
Legacy with: group
An older syntax uses a with: block inside the steps list, with container (string) and services (list of strings) properties. Do not use this for new configurations — it cannot be mixed with the step-based execution_container/service_containers syntax in the same bitrise.yml.
Building custom Docker images
Use the docker-build-push step to build and push a custom image during a workflow, which can then be referenced as a container image in subsequent builds.
Building 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.
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:
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.
Modular 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:
format_version: "25"
include:
- _workflows/shared.yml
- _workflows/ios.yml
- _workflows/android.yml
Verifying 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.ymlbitrise:validate_bitrise_yml MCP tool/validate-bitrise-yml API endpoint
- 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}
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.
Useful Links
