Using Bitrise CI

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:

# 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}

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:

• 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.

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.

• 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
  

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

• Prefer official steps to other sources. When no dedicated step is available for an action, use script:

  - 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.

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          # 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:

• Closest-wins inheritance: a Step uses its own execution_container definition first, then the parent Step bundle's, then the grandparent's. Only one execution container activates per Step.
• Usage-side override: when referencing a Step bundle, setting 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
  

• File sharing: /bitrise, /root/.bitrise, and /tmp are shared between all containers and the host. Default working directory is /bitrise/src.
• Container reuse: containers are reused across steps by default; use the object form with recreate: true to force a fresh instance (see example above).

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    # object form: discard and start fresh
            - redis               # string shorthand: reuse existing instance

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:
      # 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$'

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:

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

2. If validation fails:
   • Review error messages carefully
   • Fix the issues
   • Run validation again
3. Only proceed when validation passes
4. Test locally if possible: 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.

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