Quickstart

Start using BuildPulse runners in under 5 minutes. There are 3 main steps that need to be done:

1. Initialize your BuildPulse Runner Cluster (2m)
2. Enable runners access in GitHub settings (10s)
3. Update your workflow files to use BuildPulse runners (1m)

Steps beyond step 3 are highly recommended and contribute to cutting build times, but not required.

1. Initialize your BuildPulse Runner Cluster

a. Sign up for BuildPulse

Login to BuildPulse and go through the onboarding flow, which involves installing the BuildPulse GitHub App to your GitHub organization account, and configuring basic user account settings.

tip

The BuildPulse GitHub App allows BuildPulse to register and authorize runner agents with your account to run your jobs. BuildPulse is limited to GitHub organizations and not available for personal repositories.

b. Create Runners Cluster

To initialize your runners cluster, navigate to the Runners tab and click on "Create Cluster".

c. Create Runners

Once the cluster is ready, click "Create Runner" and select the desired configuration.

2. Enable Runners access in GitHub settings

To enable BuildPulse runners to execute GitHub Actions, ensure the correct permissions are set. Go to your Organization settings and click Actions > Runner groups > Default, verifying your repository is included.

For public repositories, also select the Allow public repositories checkbox under Repository access.

Detailed steps:

1. Navigate to your organization’s main page on github.com.
2. Click on Settings beneath your organization’s name.
3. From the left sidebar, select Actions > Runner groups.
4. Choose the Default group from the Runner groups list.
5. Under Repository access, enable Allow public repositories if necessary.
6. Under Workflow access, confirm All workflows is selected.
7. Click Save to confirm your settings.

3. Update workflow files to use BuildPulse Runners

GitHub Action workflows are stored in the .github/workflows directory. In your workflow files, replace the current runner tag in the runs-on property with the BuildPulse runner tag. BuildPulse runners are fully compatible with GitHub runners and require no additional changes.

Example:

jobs:
  build:
-    runs-on: ubuntu-latest
+    runs-on: bp-ubuntu-latest-x64-4x

BuildPulse runners are available in configurations of 2, 4, 8, 16, and 32 vCPUs, and x86-6x/arm64 architectures.

Make sure to update all runs-on fields in your workflow files.

4. BuildPulse Artifact Cache (Recommended)

BuildPulse Runner cache (buildpulse/cache@v4) speeds up jobs as it's co-located with your runners, uses more advanced compression algorithms, and provides up to 150GB of storage.

Switching caches is simple:

name: Cache Node Modules
-   uses: actions/cache@v4
+   uses: buildpulse/cache@v4
    with:
      key: ${{ runner.os }}-yarn-${{ hashFiles('./yarn.lock') }}
      path: ./node_modules

See the BuildPulse Artifact cache action documentation or the GitHub repository for more information.

5. Enable Docker Build Cache (Recommended)

BuildPulse recommends using Docker build layer caching, which caches and reuses image layers from previous builds, significantly reducing build times.

To enable incremental Docker builds, update your workflow as follows:

name: Configure Docker Buildx builder
- uses: docker/setup-buildx-action@v3
+ uses: buildpulse/setup-buildx-action@v3
  id: setup_builder

You can use the builder name output of this action to configure your docker build scripts.

${{ steps.setup_builder.outputs.name }}

If you're using docker/build-push-action, replace it with buildpulse/build-push-action@v6 to make usre of the docker layer cache.

name: Build and push docker image
- uses: docker/build-push-action@v6
+ uses: buildpulse/build-push-action@v6
  with:
    tags: org/app:latest

See BuildPulse Docker Build Cache documentation for more information.

6. Enable Docker remote builders (Recommended)

BuildPulse remote docker builders run on powerful 32 or 64 core instances geared for compressing docker build times. They're already configured to use the docker layer cache, so the combination of these significantly further reduces build times.

To enable remote docker builder, update your workflow as follows:

name: Configure Docker Buildx builder
- uses: docker/setup-buildx-action@v3
+ uses: buildpulse/setup-buildx-action@v3
  id: setup_builder
  with:
    buildpulse-builder: bp-docker-builder-x64-32x

You can use the builder name output of this action to configure your docker build scripts.

${{ steps.setup_builder.outputs.name }}

If you're using docker/build-push-action, buildpulse/build-push-action@v6 will work with the remote docker builder.

name: Build and push docker image
- uses: docker/build-push-action@v6
+ uses: buildpulse/build-push-action@v6
  with:
    tags: org/app:latest

See BuildPulse Remote Docker Builders documentation for more information.

Troubleshooting

If your organization isn't visible in the BuildPulse dashboard, verify:

• The GitHub organization has SSO enabled, and your session is authenticated via the SSO provider.
• The BuildPulse GitHub app is installed correctly in your organization.
• Your GitHub user account is a member of the GitHub organization.

Still experiencing issues? Contact support@buildpulse.io.