Skip to main content

Running Bitrise builds on-premise

Abstract

You can run Bitrise builds on your own hardware or virtual environment by installing the Bitrise agent and connect it to your Bitrise Workspace. You can install the agent on both macOS and Linux.

You can run Bitrise builds on self-hosted infrastructure - that is, that hardware or virtualized environments that you control - while taking advantage of every feature the Bitrise website offers. To do so, you just need to install the Bitrise agent on your own infrastructure and connect it to your Workspace. Once that is done, you can run builds from your Bitrise account, using the Bitrise UI as usual.

bitrise-runner-diagram.png

When to use the on-premise runner

If you need to run Bitrise builds on infrastructure that you control, Bitrise offers two options: using AWS EC2 instances, or the on-premise runner option.

We only recommend using the on-premise runner if you have the necessary machines or use a cloud provider other than AWS for your infrastructure needs. The on-premise runner is NOT plug and play: you need to make sure all necessary tools and services are installed on your machines.

If you do have an AWS account for managing your infrastructure, we recommend checking our AWS offering.

Setting up Bitrise on-premise

Abstract

To be able to run Bitrise builds on your own infrastructure, you need to get the Bitrise runner from Homebrew and then configure your network to be able to access two Bitrise service endpoints.

To be able to run Bitrise builds on your own infrastructure, you need to get the Bitrise runner from Homebrew and then configure your network to be able to access two Bitrise service endpoints.

Tools and services

Please note that when using the Bitrise runner this way, you have to make sure you have all the tools you need installed on the machine. For now, we don't provide preinstalled tools for this on-premise solution.

macOS

Linux

  1. Configure Bitrise runner pools in your Workspace settings page on bitrise.io: Configuring runner pools for self-hosted builds.

    Make sure to get the token from the process.

  2. Fetch the bitrise-den-agent formula from Homebrew.

    brew tap bitrise-io/den-agent

  3. Install the latest version.

    brew install bitrise-den-agent

    Installing a specific version

    You can also install a specific version by amending the version number to the command:

    brew install [email protected]

  4. Install the Bitrise CLI. The CLI runs the builds based on YAML configurations.

    brew install bitrise

  5. Configure your network to be able to access the following two services:

    • https://den.services.bitrise.io

    • https://build-log.services.bitrise.io

    The agent needs to be able to access both of these to run your builds and communicate with the Bitrise website.

  6. Generate a service daemon template.

    You need the runner pool token to finish the process.

    brew create-daemon --bitrise-agent-intro-secret=YOUR_AGENT_POOL_TOKEN

  7. Connect the runner on your machine to your Bitrise workspace.

    sudo mkdir -p ~/Library/LaunchDaemons 
sudo chown root:wheel ~/Library/LaunchDaemons 
sudo cp /opt/homebrew/io.bitrise.self-hosted-agent.plist ~/Library/LaunchDaemons 
sudo chown root:wheel ~/Library/LaunchDaemons/io.bitrise.self-hosted-agent.plist 
sudo launchctl load -w ~/Library/LaunchDaemons/io.bitrise.self-hosted-agent.plist

We provide the Linux Bitrise Runner binary with x86_64 architecture only since Google isn’t supporting arm64 with Android tools yet. You can vote in this Google issue to change this.

On your Apple Silicon machine, you can run the Linux Bitrise Runner with docker using the correct flags: --platform linux/x86_64.

If you require an arm64 Linux Bitrise Runner binary, please visit the Bitrise Roadmap and cast your vote.

  1. Download the Bitrise CLI binary with curl and make it executable.

    curl -fL https://github.com/bitrise-io/bitrise/releases/latest/download/bitrise-$(uname -s)-$(uname -m) > /usr/local/bin/bitrise

chmod +x /usr/local/bin/bitrise

  2. Configure Bitrise runner pools in your Workspace settings page on bitrise.io: Configuring runner pools for self-hosted builds.

    Make sure to get the token from the process.

  3. Add a GPG public key.

    curl -fsSL https://bitrise-den-agent-deb.s3.amazonaws.com/DEB-GPG-KEY-bitrise.pub | 
sudo gpg --dearmor -o /usr/share/keyrings/DEB-GPG-KEY-bitrise.gpg

  4. Add the Bitrise DEN agent deb package repository.

    echo 'deb [arch=amd64 signed-by=/usr/share/keyrings/DEB-GPG-KEY-bitrise.gpg] https://bitrise-den-agent-deb.s3.amazonaws.com stable main' | 
sudo tee /etc/apt/sources.list.d/den-agent-deb.list

  5. Install the runner and connect it on your machine to your Bitrise workspace.

    You need the runner pool token to finish the process.

    sudo apt update
sudo apt install bitrise-den-agent
/usr/bin/bitrise-den-agent-configure.sh YOUR_AGENT_POOL_TOKEN
In this section: