add PAR script action

config/_default/menus/main.en.yaml

@@ -2852,11 +2852,16 @@ menu:
       parent: private_actions
       identifier: use_private_actions
       weight: 201
+    - name: Run a Script
+      url: actions/private_actions/run_script/
+      parent: private_actions
+      identifier: run_script
+      weight: 202
     - name: Private Action Credentials
       url: actions/private_actions/private_action_credentials/
       parent: private_actions
       identifier: private_actions_creds
-      weight: 202
+      weight: 203
     - name: Cloudcraft
       url: datadog_cloudcraft/
       pre: cloudcraft

content/en/actions/private_actions/_index.md

@@ -14,6 +14,9 @@ further_reading:
 - link: "actions/private_actions/use_private_actions"
   tag: "Documentation"
   text: "Use Private Actions"
+- link: "actions/private_actions/run_script"
+  tag: "Documentation"
+  text: "Run a Script with the Private Action Runner"
 - link: "actions/private_actions/private_action_credentials"
   tag: "Documentation"
   text: "Handling Private Action Credentials"

content/en/actions/private_actions/run_script.md

@@ -0,0 +1,239 @@
+---
+title: Run a Script with the Private Action Runner
+disable_toc: false
+aliases:
+- service_management/workflows/private_actions/run_script
+- service_management/app_builder/private_actions/run_script
+---
+
+## Overview
+
+The private action runner (PAR) script action 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.
+
+<div class="alert alert-warning">
+<strong>Security Notice:</strong> The PAR script action runs within a containerized environment using a dedicated Linux user named `scriptuser` for enhanced security. Datadog enforces container sandboxing and only accepts signed tasks, but you decide which binaries and scripts are allowed. Always review every command you add to the script action allow-list, especially ones that take dynamic user input. Ensure that your actions are configured with the least privileged commands, and carefully review the permissions you share through connections. For more information, see <a href="/actions/connections/?tab=workflowautomation#connection-security-considerations">connection security considerations</a>.
+</div>
+
+## Use cases
+
+The following table outlines supported and unsupported use cases for the script action:
+
+| Use Case                                            | Supported | Notes                                                                                                                        |
+|-----------------------------------------------------|-----------|------------------------------------------------------------------------------------------------------------------------------|
+| Running Linux binaries (`ls`, `rm`, `find`, `curl`) | Yes   | In order to run native Linux binaries, the relevant files must be accessible to the container.          |
+| Running CLIs (`aws`, `terraform`, `kubectl`)        | Yes   | The CLI and your CLI credentials must be added to your custom image.                                                       |
+| Running scripts (`bash`, `python`)                  | Yes   | Scripts can be mounted inside the container. Interpreters such as Python must be installed on your custom image. |
+| Running privileged commands (`systemctl restart`)   | No    | Because the PAR runs inside a container, it does not have high privilege permissions on the host.                                         |
+| Windows tools (PowerShell)                          | No    | Because the PAR runs inside a Linux container, native Windows tools are not supported.                                             |
+
+## 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. See [set up a private action runner][2] to get started.
+- anything else? 🤨
+
+## Set up a PAR script
+
+### 1. Update your runner image
+
+Replace the standard PAR image with the development image that supports script actions. The development images are published on [Docker Hub][2].
+
+**Standard image:**
+```
+gcr.io/datadoghq/private-action-runner:v1.3.0
+```
+
+**Script-enabled image:**
+```
+datadog/private-action-runner-dev:latest@sha256:4e990e496b79d02514c19a633042d27be1ba8e7a4b9018efd0e942ed1a070ad8
+```
+
+You can either reuse an existing runner's identity by changing the image, or create a brand new runner.
+
+### 2. Create a script connection
+
+1. Navigate to the **Private Action Runner** page in [Workflow Automation][4] or [App Builder][5].
+1. Create a new script connection and associate it with your private action runner.
+1. Select this connection when using the script action in your workflows or apps.
+
+### 3. Configure the action catalog
+
+Navigate to the Action Catalog and select [**Run Predefined Script**][10]. This action is available for use in both workflows and apps.
+
+## Configuration
+
+Configure script actions through your runner's `config.yaml` file. If you create a new runner and select the script bundle, you get a default configuration.
+
+### Basic configuration
+
+```yaml
+# Add the script action to the allowlist
+actionsAllowlist:
+  - com.datadoghq.script.runPredefinedScript
+
+# Configure different scripts
+bundles:
+  "com.datadoghq.script":
+    runPredefinedScript:
+      echo:
+        command: ["echo", "Hello world"]
+      # Use workflow-like syntax to retrieve values from parameters
+      echo-parametrized:
+        command: ["echo", "{{ parameters.echoValue }}"]
+      echo-nested-parametrized:
+        command: ["echo", "{{ parameters.nested.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
+# Dockerfile example
+FROM gcr.io/datadoghq/private-action-runner:v1.7.0
+RUN apt update && apt install -y python3
+```
+
+You can mount complex scripts inside the runner:
+
+```yaml
+# docker-compose example
+services:
+  runner:
+    image: gcr.io/datadoghq/private-action-runner:v1.7.0
+    volumes:
+      - "./config:/etc/dd-action-runner/config"
+      - "./scripts:/etc/dd-action-runner-script/scripts:ro"
+```
+
+```yaml
+# 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" ]
+```
+
+## Update the PAR 
+
+<!-- ADD INFO? -->
+
+To view the latest version of the PAR, check [this URL][6].
+
+### Docker mode
+Navigate to the directory where you started the PAR. Next, navigate to the `config` directory, then the `config.yaml` file. 
+
+
+Find the current ID of your container:
+```bash
+docker ps
+```
+
+Stop the container:
+```bash
+docker stop <id>
+```
+
+Start a new container with [the latest image][6]. Environment variables are no longer needed. Everything is configured in the `config/config.yaml` file.
+
+Run:
+```bash
+docker run -d  -u 0 --platform=linux/x86_64  -p 9016:9016  -v ./config:/etc/dd-action-runner  --health-cmd "curl http://localhost:9016/liveness"  --health-interval 10s  --health-timeout 10s  --health-retries 3 gcr.io/datadoghq/private-action-runner:v1.0.0
+```
+
+After confirming the new PAR version is working as expected, remove the old version:
+```bash
+docker rm <id>
+```
+
+To check the PAR logs: 
+```bash
+docker logs <id-of-container>
+```
+
+### Docker compose mode
+Navigate to the directory containing your `docker-compose.yaml` file. Next, navigate to the `config` directory, then the `config.yaml` file. Update the `image` property of the PAR and point to the latest version:
+
+```yaml
+services:
+  private-actions-runner:
+    image: gcr.io/datadoghq/private-action-runner:<latest_version>
+    cpus: 25
+    mem_limit: 1g
+    deploy:
+      replicas: 1
+    environment:
+      - DD_BASE_URL=https://app.datadoghq.com
+      - DD_PRIVATE_RUNNER_CONFIG_DIR=/etc/dd-action-runner/config 
+      - RUNNER_ENROLLMENT_TOKEN=<the_token>
+      - STATSD_ENABLED=true
+    volumes:
+      - "./config:/etc/dd-action-runner/config"
+
+Start the container again:
+```bash
+docker compose up -d
+```
+
+To check the logs:
+```bash
+docker compose logs runner
+```
+
+### Helm mode
+When using Helm, there are two options for upgrading the PAR: 
+1. **(Recommended)** Upgrade the chart, which will use the latest version of the PAR. There may be changes to the chart; please review [our changelog][8].
+1. Upgrade the runner without upgrading the chart.
+
+#### Upgrading the chart (recommended)
+
+Navigate to the directory containing your `values.yaml` file and run:
+
+```bash
+helm repo update
+helm upgrade <RELEASE_NAME> datadog/private-action-runner -f ./values.yaml
+```
+
+#### Upgrading the PAR only
+
+Specify the PAR version in your `values.yaml` under the `common.image.tag` key with the values found [here][9]:
+
+```yaml
+common:
+  image:
+    repository: gcr.io/datadoghq/private-action-runner # optional
+    # latest image https://api.datadoghq.com/api/v2/on-prem-management-service/runner/latest-image
+    tag: v1.0.0
+```
+
+Then run: 
+```bash
+helm upgrade <RELEASE_NAME> datadog/private-action-runner -f ./values.yaml
+```
+
+To check the logs: 
+```bash
+kubectl get pods
+kubectl logs <name-of-the-pod>
+```
+
+[1]: /actions/private_actions/use_private_actions/?tab=docker#supported-private-actions
+[2]: /actions/private_actions/use_private_actions/#set-up-a-private-action-runner
+[3]: https://hub.docker.com/r/datadog/private-action-runner-dev
+[4]: https://app.datadoghq.com/workflow/
+[5]: https://app.datadoghq.com/app-builder/
+[6]: https://api.datadoghq.com/api/v2/on-prem-management-service/runner/latest-image
+[7]: https://app.datadoghq.com/organization-settings/remote-config?resource_type=agents
+[8]: https://github.com/DataDog/helm-charts/blob/main/charts/private-action-runner/CHANGELOG.md
+[9]: https://github.com/DataDog/helm-charts/blob/main/charts/private-action-runner/values.yaml
+[10]: https://app.datadoghq.com/actions/action-catalog#/com.datadoghq.script.runPredefinedScript