Set Up a Standalone Private Action Runner

Docs > Actions > Private Actions > Set Up a Standalone Private Action Runner

Overview

The standalone private action runner is a dedicated container you can install and manage independently of the Datadog Agent with Docker or Helm. It is supported and in maintenance mode: it continues to receive security and stability updates, and no new features are planned. For new deployments, and to use Execution Policies, run the runner in the Datadog Agent instead. See Set up a private action runner in the Datadog Agent.

Setting up the runner takes three steps:

Install the runner with Docker, Docker Compose, or Kubernetes.
Connect the runner to Datadog with a connection.
Update the runner as new versions are released.

A standalone runner is always owned: creating one, through either method below, always registers it under the creating user, authorized with Connections.

Prerequisites

Docker, or a Kubernetes cluster.
Network access to Datadog at https:// and https://config..

Install the runner

In Datadog, navigate to Action Catalog > Private Action Runners, and click New Private Action Runner.
Enter a name for your runner and select the allowed actions.
Create a directory on your host where the runner can store its configuration, such as ./config.
Deploy your runner by following the steps for your container platform:

Click Docker.
Run the provided docker run command on your host, replacing ./config with the path to the directory you created for the runner configuration.

Note: You can safely ignore the error DATADOG TRACER DIAGNOSTIC - Agent Error: connect ECONNREFUSED.

Click Docker Compose.
Create a docker-compose.yaml file and add the provided YAML, or add the runner stanza to an existing Docker Compose file.
Replace ./config with the path to the directory you created for the runner configuration.
Run docker compose up -d.

Note: You can safely ignore the error DATADOG TRACER DIAGNOSTIC - Agent Error: connect ECONNREFUSED.

Click Kubernetes.
Confirm that kubectl and helm are installed, and that you have sufficient permissions to create Kubernetes resources in your cluster.
Follow the instructions provided in the app to enroll the runner, generate the config, add the Private Action Runner Helm repository, and install the chart.
Run kubectl get pods -w and verify the private action runner pod’s status becomes Ready.

Alternative: programmatic installation

As an alternative to the UI-based setup above, you can enroll and configure a standalone runner programmatically using your API key and application key. This approach is suited to automated deployments, CI/CD pipelines, and infrastructure-as-code workflows. Like the UI-based setup, this always creates an owned runner. Despite the --with-api-key flag’s name, this path still requires an application key: the runner uses both credentials together to register itself and assign the application key’s owner as the runner’s Editor.

To set up the runner programmatically:

Provide your Datadog API and application keys through the DD_API_KEY and DD_APP_KEY environment variables.
Pass the --with-api-key flag to the runner container.

export DD_API_KEY="<YOUR_API_KEY>"
export DD_APP_KEY="<YOUR_APP_KEY>"

docker run -d \
  -e DD_BASE_URL=https://<span class="js-region-param region-param" data-region-param="dd_site"></span> \
  -e DD_PRIVATE_RUNNER_CONFIG_DIR=/etc/dd-action-runner/config \
  -e DD_API_KEY="$DD_API_KEY" \
  -e DD_APP_KEY="$DD_APP_KEY" \
  -e RUNNER_NAME=<YOUR_RUNNER_NAME> \
  -v ./config:/etc/dd-action-runner/config \
  gcr.io/datadoghq/private-action-runner:v1.21.0 \
  --with-api-key

services:
  private-runner:
    image: gcr.io/datadoghq/private-action-runner:v1.21.0
    command: ["--with-api-key"]
    environment:
      DD_API_KEY: ${DD_API_KEY}
      DD_APP_KEY: ${DD_APP_KEY}
      DD_BASE_URL: https://<span class="js-region-param region-param" data-region-param="dd_site"></span>
      DD_PRIVATE_RUNNER_CONFIG_DIR: /etc/dd-action-runner/config
      RUNNER_NAME: my-compose-runner
    volumes:
      - "./config:/etc/dd-action-runner/config"

Run with:

export DD_API_KEY="<YOUR_API_KEY>"
export DD_APP_KEY="<YOUR_APP_KEY>"
docker compose up -d

Generate the runner configuration:

export DD_API_KEY="<YOUR_API_KEY>"
export DD_APP_KEY="<YOUR_APP_KEY>"

docker run \
  -e DD_BASE_URL=https://<span class="js-region-param region-param" data-region-param="dd_site"></span> \
  -e DD_PRIVATE_RUNNER_CONFIG_DIR=/etc/dd-action-runner/config \
  -e DD_API_KEY="$DD_API_KEY" \
  -e DD_APP_KEY="$DD_APP_KEY" \
  -e RUNNER_NAME="my-runner" \
  -v ./config:/etc/dd-action-runner/config \
  gcr.io/datadoghq/private-action-runner:v1.21.0 \
  --with-api-key --enroll -f helm-values > values.yaml

Deploy the Helm chart:

helm upgrade --install <RELEASE_NAME> datadog/private-action-runner -f values.yaml

When the runner shows Ready to use, create a connection for it, or view it on the Private Action Runners page.

Custom CA certificates

If your organization uses a custom certificate authority (CA) to issue certificates for internal services, such as HTTP endpoints or Jenkins, you can configure a standalone private action runner to trust that CA.

Add the SSL_CERT_DIR environment variable and mount your certificate to the docker run command, replacing <PATH_TO_YOUR_CA_CERTIFICATE> with the path to your CA certificate file:

docker run -d \
  -e DD_BASE_URL=https://<span class="js-region-param region-param" data-region-param="dd_site"></span> \
  -e DD_PRIVATE_RUNNER_CONFIG_DIR=/etc/dd-action-runner/config \
  -e DD_API_KEY="$DD_API_KEY" \
  -e DD_APP_KEY="$DD_APP_KEY" \
  -e RUNNER_NAME=<YOUR_RUNNER_NAME> \
  -e SSL_CERT_DIR=/etc/dd-action-runner/config/ca-certificates \
  -v ./config:/etc/dd-action-runner/config \
  -v <PATH_TO_YOUR_CA_CERTIFICATE>:/etc/dd-action-runner/config/ca-certificates/ca.crt \
  gcr.io/datadoghq/private-action-runner:v1.21.0 \
  --with-api-key

Add the SSL_CERT_DIR environment variable and mount your certificate in your docker-compose.yaml file, replacing <PATH_TO_YOUR_CA_CERTIFICATE> with the path to your CA certificate file:

services:
  private-runner:
    environment:
      SSL_CERT_DIR: /etc/dd-action-runner/config/ca-certificates
    volumes:
      - "<PATH_TO_YOUR_CA_CERTIFICATE>:/etc/dd-action-runner/config/ca-certificates/ca.crt"

Create a ConfigMap containing your CA certificate:

kubectl create configmap my-ca-cert --from-file=ca.crt=./my-custom-ca.pem

In your Helm values.yaml file, reference the ConfigMap:

runner:
  customCaCert:
    configMapName: my-ca-cert

Apply the updated values:

helm upgrade --install <RELEASE_NAME> datadog/private-action-runner -f values.yaml

Connect the runner

A standalone runner is always owned and uses the Connections authorization model. A connection stores the credentials for a service and pairs them with the runner. To create a connection and pair it with your runner, see Connections. For how permissions on the runner itself work, see Manage access to owned runners.

Manage the runner

Edit connections or delete a runner

From the Private Action Runner page in Action Catalog, you can view all your private runners together with the workflows or apps that use each one. To edit the connections for a runner, click View Details. Click the trash can icon to delete a runner.

Change the allowlist

To edit the allowlist for a standalone runner, edit the actionsAllowlist section of the config.yaml file in your runner’s environment, then restart the runner by restarting your container or deployment.

Update the runner

Choose the tab that matches how you installed the runner. Use the current v1.21.0 version rather than a hardcoded tag.

Find the current ID of your container:

docker ps

Stop the container:

docker stop <id>

Start a new container with the latest image. Environment variables are not needed: everything is configured in the config/config.yaml file.

docker run -d \
  -e DD_PRIVATE_RUNNER_CONFIG_DIR=/etc/dd-action-runner/config \
  -v ./config:/etc/dd-action-runner/config \
  gcr.io/datadoghq/private-action-runner:v1.21.0

After confirming the new version is working, remove the old container:

docker rm <id>

Navigate to the directory containing your docker-compose.yaml file and update the image version:

services:
  private-actions-runner:
    image: gcr.io/datadoghq/private-action-runner:v1.21.0

Start the container again:

docker compose up -d

There are two options for upgrading with Helm:

(Recommended) Upgrade the chart, which uses the latest version of the runner. There may be changes to the chart; review the changelog.
Upgrade the runner only, without upgrading the chart.

Upgrading the chart (recommended):

helm repo update
helm upgrade <RELEASE_NAME> datadog/private-action-runner -f ./values.yaml

Upgrading the runner only: specify the runner version in values.yaml under the common.image.tag key with a value from the chart’s values file:

common:
  image:
    tag: v1.21.0

Then run:

helm upgrade <RELEASE_NAME> datadog/private-action-runner -f ./values.yaml