Get started with Edge Runners

Edge Runners are lightweight execution agents that run inside customer environment and allow CloudBees Unify to execute tasks against private systems that are not directly accessible from the Unify environment. They effectively provide a secure bridge between Unify and private infrastructure. For example, an Edge runner deployed inside a customer’s network can allow a CloudBees workflow to trigger a CloudBees CI pipeline that sits behind the customer’s firewall or integrate Unify with private SCMs without exposing these systems publicly.

In this tutorial you will set up CloudBees Unify Edge Runners on your own machine and register them in your organization. By the end, you will have at least one running Edge runner that polls CloudBees Unify for jobs and executes them on your infrastructure.

Edge runners are only available in paid plans.

Prerequisites

Before you begin, ensure that you have the following prerequisites in place:

Only users with READ Edge runners permission can access the Edge runners view in CloudBees Unify’s interface.
- By default, this permission is enabled for Admin and User roles.
- By default, these permissions are enabled for the Admin role.
Only users with CREATE Edge runners permission can register Edge runners.
- By default, this permission is enabled for the Admin role.
Only users with DELETE Edge runners permission can un-register Edge runners.
- By default, this permission is enabled for the Admin role.
Custom roles with the desired Edge runners permissions can be managed in the RBAC management section in CloudBees Unify.
A machine to host the Edge runner. This can be a physical server, virtual machine, or cloud instance that is able to run the Edge runner binary. Ensure there is network connectivity to the private tools that you intend to reach in jobs running in this Edge runner.
- Be sure to provision a machine with sufficient resources (CPU, memory, and storage) to handle the expected job workloads. For more information, refer to Edge Runners hardware requirements.
- Be sure the provisioned machine has Docker engine installed and running, if you plan to use the Docker execution mode for jobs. For more information, refer to Binary: --execution mode.
Verify your code execution trust model
- When executing jobs on edge runners, it’s important to consider the trust model of the code being executed. Edge runners execute arbitrary commands as defined in the workflow sent by CloudBees Unify. This means that any user who can create and execute workflows in organizations where runners are available can execute scripts on the runner.
  
  Organizations should deploy Edge runners with the appropriate isolation and security measures, based on their security requirements.

Set up an edge runner

Follow the steps below to set up an edge runner on your machine and register it in CloudBees Unify.

Obtain a JSON web token, by either creating a personal access token (PAT) or generating a registration token in the CloudBees Unify interface:

Create a personal access token (PAT)

Create a personal access token (PAT) in CloudBees Unify under User Profile Personal Access Tokens Generate Token.
Save this token to a file, for example, ~/cloudbees-unify-pat.txt.
Navigate to the desired organization or sub-organization where you want to set up edge runners.

Be aware that runners created at the organization level are available for use within that organization as well as all associated sub-organizations.
Record the organization ID from Admin settings Organization profile.

Obtain an edge runner registration token using the CloudBees Unify API with your PAT:

Here is an example of a curl script using jq to parse the result:

$ curl -X POST "https://api.cloudbees.io/v1/organizations/<org ID from step 2>/edge/runner-token" \
-H "Authorization: Bearer $(cat ~/cloudbees-unify-pat.txt)" \
-H "Content-Type: application/json" | jq -r '.access_token' > ~/cloudbees-unify-runner-creation-token.txt▼

Auto-generate a token

Select the Generate registration token button in the CloudBees Unify interface to generate a new edge runner registration token for your organization or sub-organization.
Copy the generated token and save it to a file, for example, ~/cloudbees-unify-runner-creation-token.txt.
Select Done to close the dialog.

A generated token is valid for one hour and can be used to register multiple runners. After this period, the token will expire, and a new token must be created to register additional edge runners.

Download the edge runner binary:
- Linux AMD64

Verify the runner binary, by doing the following:

Use the following public key to verify the signature of the downloaded binary:

Save the public key to cosign.pub, for example:

export PLATFORM=linux/amd64
wget https://downloads.cloudbees.com/pub/unify-edge-runner/releases/stable/$PLATFORM/cloudbees-runner
wget https://downloads.cloudbees.com/pub/unify-edge-runner/releases/stable/$PLATFORM/cloudbees-runner.sigstore.json
wget https://downloads.cloudbees.com/pub/unify-edge-runner/releases/stable/$PLATFORM/cloudbees-runner.att.json▼

Verify the signature and SLSA attestation using cosign:

cosign verify-blob --bundle cloudbees-runner.sigstore.json --key cosign.pub cloudbees-runner --insecure-ignore-tlog=true
cosign verify-blob-attestation --type slsaprovenance1 --bundle cloudbees-runner.att.json --key cosign.pub cloudbees-runner --insecure-ignore-tlog=true▼

Mark the runner binary as executable, for example:
```
chmod +x ./cloudbees-runner▼
```

Configure the runner and register it in CloudBees Unify using the binary. Here is an example, with common flags specified:

$ ./cloudbees-runner configure --working-dir ~/my-runner/ --labels my-label-1,my-label-2 --token-stdin < ~/cloudbees-unify-runner-creation-token.txt▼

Edge runners offer two job execution modes: native and Docker (by default). The available modes are selected when the runner is registered.

For more information on Job execution isolation, refer to Secure: Job execution isolation or Binary: --execution mode.

Start the runner using the binary. The runner polls CloudBees Unify for jobs to execute. Here is an example:
```
$ ./cloudbees-runner run --working-dir ~/my-runner/▼
```

Now your Edge runner is polling for work to execute. Use it to run workflow jobs on-premise and for enabling integrations with private SCMs.

For more information on executing jobs or platform integrations, refer to Execute jobs with Edge Runners or Configure private SCM integrations.

Now your Edge runner is polling for work to execute. You can use it to run workflow jobs on premise and also for enabling integrations with private SCMs. For more information, refer to docs/cloudbees-unify/latest/edge-runners/how-to-guides/execute-jobs-with-edge-runners and platform-integration/how-to-guides/configure-source-code-management#_configure_private_scm_integrations.

Use the -help command, or --h in the binary, to explore additional commands and options. For more information, refer to Edge Runners binary reference.