Overview

This page explains how to use the private action runner (PAR), which allows you to run custom scripts and Linux binaries within your Datadog workflows and apps. Unlike standard private actions that call specific APIs or services, the script action gives you the flexibility to execute arbitrary commands, shell scripts, and command-line tools directly from the private action runner in your private network.

Use cases

The following table outlines supported and unsupported use cases for the script action:

Prerequisites

To use the script action, you need:

• Custom tools: For CLI tools not included in the base image, you need to create a custom Docker image.
• PAR Version: 1.7.0 or later. To create a new PAR, see Set Up a Private Action Runner. To update your PAR version, see Update the Private Action Runner.

Set up a PAR script

Create a script connection

1. After setting up a PAR, navigate to Connections.
2. Click New Connection.
3. Select Script.
4. Enter a Connection Name.
5. In the Private Action Runner dropdown, select your PAR.
6. Copy and paste the credential file template into your PAR’s configuration directory with the commands you want to run.
7. In Path to file, ensure the file path matches the path on your runner’s filesystem (the default should be sufficient in most use cases).
8. Click Next, Confirm Access.
9. After configuring permissions, click Create.
10. Select this new connection when using the script action in your workflows or apps.

Configuration

Configure script actions through your runner’s config.yaml file and the script connection (credentials/script.yaml by default). If you create a new runner and select the script bundle, you get a default configuration.

# Add the script action to the allowlist (`config.yaml`)
actionsAllowlist:
  - com.datadoghq.script.runPredefinedScript

# Configure your script connection (`credentials/script.yaml`)
schemaId: script-credentials-v1
runPredefinedScript:
  # use "echo" as the "Script name" in the action configuration
  echo:
    # use an array to specify the command
    command: ["echo", "Hello world"]

  # another script
  echo-parametrized:
    # you can use workflow syntax (https://docs.datadoghq.com/actions/workflows/variables/) to retrieve values from the parameters object
    command: [ "echo", "{{ parameters.echoValue }}" ]
    # you can use JSON schema (https://json-schema.org/) to validate the parameters
    parameterSchema:
      properties:
        echoValue:
          type: string
          const: "world"
      required:
        - echoValue

Using the configured scripts

In your workflow or app, configure the action to use the runPredefinedScript with the script name you defined (for example, echo or echo-parametrized).

Note: There are two levels of variable resolution: one at the workflow level and one at the action level inside the runner.

Advanced usage with custom images

For binaries not available in the base runner image, create a custom image:

# Dockerfile example
FROM gcr.io/datadoghq/private-action-runner:v1.9.0
USER root
RUN apt update && apt install -y python3
USER dog

You can mount complex scripts inside the runner:

# docker-compose example
services:
  runner:
    image: gcr.io/datadoghq/private-action-runner:v1.9.0
    # build: . # if you are using a custom Dockerfile
    volumes:
      - "./config:/etc/dd-action-runner/config"

# credentials/script.yaml
schemaId: script-credentials-v1
runPredefinedScript:
  python:
    command: ["python3", "/etc/dd-action-runner-script/scripts/script.py"]
  shell:
    command: [ "bash", "/etc/dd-action-runner-script/scripts/script.sh" ]

# scripts/script.sh
echo "Hello from the shell script!"

# scripts/script.py
print("Hello from Python script!")