Terminal
Terminal/Skill
Teaches your agent how to set up, run and troubleshoot Bitrise CI builds, edit bitrise.yml files, and manage workspaces and apps.
By Bitrise
Works with
npx skills add bitrise-io/agent-skills --skill using-bitrise-ciAn 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.
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.
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 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:
# 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}
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.
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.
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.
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.
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.secrets.yml.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.containers defines Docker execution and service containers available to Steps and Step bundles (Linux only)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:
app:
envs:
- PROJECT_NAME: MyApp
- BUNDLE_ID: com.example.myapp
- VERSION: 1.0.0
meta block is required for running builds on Bitrise:
meta:
bitrise.io:
stack: linux-docker-android-22.04
Workflows contain a list of steps with optional configuration and conditions.
get sources -> build -> test -> publish or deploy.activate-ssh-key and git-clone steps.custom-test-results-export is needed to convert the results, and deploy-to-bitrise-io to upload them to Bitrise for reporting. 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.*'
script:
- script@1:
title: Print build info
inputs:
- content: |
echo "Building branch: $BITRISE_GIT_BRANCH"
bitrise:step_search tool or the /search-steps endpoint to find steps.git-clone@8), this guards against breaking changes but allows bug fixes. Use the step search tools to verify.bitrise:step_inputs tool or the /step-inputs endpoint to get data about the step inputs.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 ""}}
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 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.
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 # 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
Key behaviors:
execution_container definition first, then the parent Step bundle's, then the grandparent's. Only one execution container activates per Step.execution_container at the call site overrides the container defined inside the bundle definition. Override priority is: Step-level > bundle call-site > bundle definition.
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, and /tmp are shared between all containers and the host. Default working directory is /bitrise/src.recreate: true to force a fresh instance (see example above).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 # object form: discard and start fresh
- redis # string shorthand: reuse existing instance
Key behaviors:
service_containers at the bundle call-site overrides the service containers defined inside the bundle definition.bitrise Docker network.
http://postgres:5432).localhost (e.g., http://localhost:5432).Store Docker registry credentials as Secrets and reference them in the credentials block (username, password, and optionally server for non-Docker Hub registries).
The --network, --volume (-v), and --entrypoint Docker options are not supported in the options field.
with: groupAn 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.
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.
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.
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:
# 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$'
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.
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
Use this workflow:
bitrise validate -c bitrise.ymlbitrise:validate_bitrise_yml MCP tool/validate-bitrise-yml API endpointbitrise run {workflow_id}