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](https://docs.bitrise.io/en/bitrise-platform/accounts/personal-access-tokens.html) or [workspace](https://docs.bitrise.io/en/bitrise-platform/workspaces/workspace-api-token.html#creating-a-workspace-api-token) 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](https://docs.bitrise.io/en/bitrise-ci/api/api-reference.html). 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](https://github.com/bitrise-io/bitrise/releases) 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 # 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](https://bitrise.io/integrations). **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](https://docs.bitrise.io/en/bitrise-ci/references/available-environment-variables.html) 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](https://docs.bitrise.io/en/bitrise-platform/integrations/the-service-credential-user.html) 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](https://docs.bitrise.io/en/bitrise-ci/api/adding-and-managing-apps.html). ### Adding a project interactively from CLI If the user prefers so, the [bitrise-add-new-project](https://docs.bitrise.io/en/bitrise-ci/bitrise-cli/adding-a-new-project-from-a-cli.html) 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](https://github.com/SchemaStore/schemastore/blob/master/src/schemas/json/bitrise.json) for the JSON schema or [this page](https://docs.bitrise.io/en/bitrise-ci/references/configuration-yaml-reference.html) 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: ```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 ``` ### 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](https://docs.bitrise.io/en/bitrise-ci/testing/deploying-and-viewing-test-results.html). - Dependencies can be cached between builds for better performance. Popular package managers have dedicated caching steps, others require manual configuration. Details [here](https://docs.bitrise.io/en/bitrise-ci/dependencies-and-caching/dependencies-and-caching-overview.html). 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.*' ``` #### Using 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. #### 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 ""}}` #### 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.** ### 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`: ```yaml 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): ```yaml 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**. ```yaml 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`: ```yaml 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): ```yaml 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