Use the Bitrise step

Use Bitrise Workflow Steps in your Harness CI pipelines.

With the Bitrise plugin step (also called the Bitrise step), you can use Bitrise Workflow Steps in your Harness CI pipelines. For more information about plugins in CI pipelines, go to Explore plugins.

Currently, the Bitrise plugin step is supported for Harness Cloud build infrastructure only. For other build infrastructures, you can run Bitrise Workflow Steps in a Run step or write a custom plugin.

Bitrise step usage example

In the following YAML example, a Harness Bitrise step runs the Android Build Bitrise step. It calls the source repo (bitrise-steplib/bitrise-step-android-build) and provides configuration parameters as described in the Android Build README.

              - step:
                  type: Bitrise
                  name: bitrise android build
                  identifier: bitrise_android_build
                  spec:
                    uses: github.com/bitrise-steplib/bitrise-step-android-build.git
                    with:
                      variant: 'debug'
                      build_type: 'apk'

Bitrise step settings and specifications

Add a Bitrise step to your pipeline, for example:

              - step:
                  type: Bitrise
                  name: bitrise android build
                  identifier: bitrise_android_build
                  spec:
                    uses: github.com/bitrise-steplib/bitrise-step-android-build.git
                    with:
                      variant: 'debug'
                      build_type: 'apk'

The spec parameters define which Bitrise Step to use, the Bitrise Step inputs, and the environment variables that you want to pass in. These are configured according to the Bitrise Step's usage specifications.

uses: Specify the Bitrise Steps's source repo, such as github.com/bitrise-steplib/bitrise-step-android-build.git.
with: If required by the Bitrise Step, provide a mapping of key-value pairs representing inputs, such as build_type: 'apk'. For more information, go to Settings.
env: If required by the Bitrise Step, provide a mapping of environment variables to pass in. For more information, go to Environment Variables.

If you already configured Bitrise Steps elsewhere, you can transfer Bitrise Steps into Harness CI.

You can use expressions in the with and env settings. For example, credentials: <+stage.variables.[TOKEN_SECRET]> uses an expression referencing a stage variable.

In the Visual editor, add the Bitrise plugin step to your pipeline's Build stage, and then populate the settings. Name and Uses are required. Refer to each Bitrise Step's documentation for information about Settings and Environment Variables.

Name

Enter a name summarizing the step's purpose. Harness automatically assigns an Id (Entity Identifier Reference) based on the Name. You can change the Id.

The Description is optional.

Uses

Specify the repo of the Bitrise Step that you want to use, for example github.com/bitrise-steplib/bitrise-step-android-build.git.

Settings

If required by the Bitrise Step, add key-value pairs representing inputs, such as build_type: 'apk'. Refer to your chosen Bitrise Step's usage specifications for details about specific inputs available for the Bitrise Step that you want to use.

Settings keys can be supplied as fixed values or runtime input, and values can be supplied as fixed values, runtime input, or expressions. For more information, go to Fixed values, runtime inputs, and expressions.
In the Visual editor, there are separate fields for keys and values. For example, to specify build_type: 'apk' in the Visual editor, you would enter build_type in the key field and apk in the value field.

Environment Variables

If required by the Bitrise Step, add key-value pairs representing environment variables that you want to pass to the Bitrise Step, such as GITHUB_TOKEN: <+secrets.getValue("github_pat")>.

These are incoming environment variables that you're passing to the Bitrise Workflow Step. These are separate from outgoing environment variables that might be produced by the Bitrise Step you're using. Refer to your chosen Bitrise Step's usage specifications for details about specific environment variables relevant to the Bitrise Step that you want to use.

You can use fixed values, runtime inputs, or expressions for environment variable values. For example, <+stage.variables.[TOKEN_SECRET]> is a variable expression stage variable.
In the Visual editor, there are separate fields for keys and values. For example, to specify GITHUB_TOKEN: <+secrets.getValue("github_pat")> in the Visual editor, you would enter GITHUB_TOKEN in the key field and <+secrets.getValue("github_pat")> in the value field.

Empty environment variables

Currently, support for empty environment variables in CI pipelines is behind the feature flag CI_USE_LESS_STRICT_EVALUATION_FOR_MAP_VARS. Contact Harness Support to enable the feature.

If your Bitrise Step requires an empty environment variable, you must contact Harness Support to enable an early access feature that allows empty environment variables in CI pipelines.

Timeout

You can set the timeout limit for the step. Once the timeout limit is reached, the step fails and pipeline execution continues. To set skip conditions or failure handling for steps, go to:

Transfer Bitrise Steps into Harness CI

If you already configured Bitrise Workflow Steps elsewhere, the Bitrise inputs mapping is equivalent to the Harness Bitrise plugin step's spec: with: mapping. The following table compares Bitrise inputs specification with the equivalent Harness with specification.

Bitrise inputs

Harness with

inputs: - variant: debug - build_type: apk

yaml with: variant: 'debug' build_type: 'apk'

Support for Bitrise Steps on VM and Local Runner Build Infrastructure

Prerequisites for self-managed VM infrastructure

To support Bitrise steps in your self-managed VM infrastructure, your build VMs must include a few additional tools at runtime.

These tools are required for the GitHub Actions/Bitrise runners embedded within the Harness build process.

Required tools

Ensure that all build VMs (those provisioned by your runner) include:

nodejs version 16 or higher
python3 (with python pointing to python3)
golang
A correctly set HOME environment variable

These are prerequisites for the Bitrise step runtimes and are not automatically installed by Harness.

Recommended: Install via user_data script

To automate provisioning of these tools, you can inject setup commands through the runner’s user_data in your pool.yml.

Here’s an example for Linux-based VMs:

user_data: |
  #cloud-config
  runcmd:
    - 'sed -i "1s|^|HOME=/home/ubuntu\n|" /etc/environment'
    - 'curl -fsSL https://deb.nodesource.com/setup_16.x | sudo -E bash -'
    - 'sudo apt install -y python3 python-is-python3 nodejs golang'

This script:

Initializes the HOME variable for login shells
Installs the required language runtimes and tooling
Prepares the VM to run GitHub Actions and Bitrise step definitions reliably

MINIMUM DELEGATE VERSION

To use Bitrise step types in Harness CI, your Harness Delegate must be version 863 or later.

Check out user-data-example for details.

Prerequisites for local runner

Starting with v0.1.19, local runners support Bitrise and GitHub Action steps.

To use this feature, make sure:

You're using runner version v0.1.19 or later.
The feature flag CI_ENABLE_PLUGIN_OUTPUT_SECRETS is enabled.
The machine has access to github.com, since the runner downloads additional binaries during execution.

PreviousPlugin step settings

NextIntegrate Jira in a CI pipeline

Last updated 11 days ago

Was this helpful?