RunsOn

https://runs-on.com/docs
Admin
RunsOn provides self-hosted GitHub Actions runners on AWS, offering fast, cheap, and secure compute,...
Tokens:134,671
Snippets:1,185
Trust Score:7.3
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Quick start: Go tests on 16cpu runner with s3-cache

Source: https://runs-on.com/docs/guides/languages/go

Minimal GitHub Actions workflow to run Go tests on a 16-vCPU RunsOn runner with S3 Magic Cache. Requires RunsOn installed; setup-go caches GOCACHE/GOMODCACHE automatically.

```yaml
jobs:
  test:
    runs-on: runs-on=${{ github.run_id }}/runner=16cpu-linux-x64/extras=s3-cache
    steps:
      - uses: runs-on/action@v2
      - uses: actions/checkout@v7
      - uses: actions/setup-go@v5
        with:
          go-version: "1.25"
      - run: go test ./...
```

--------------------------------

### Workflow runs-on examples

Source: https://runs-on.com/docs/runners/labels

Workflow examples using the runs-on key with different runner and image combinations. Ensure runner and image definitions are compatible; for example, do not mix x64 runner types with arm64 images.

```yaml
jobs:
  test:
    runs-on: runs-on=${{github.run_id}}/runner=2cpu-linux-x64/image=mycustomimage
```

```yaml
jobs:
  test:
    runs-on: runs-on=${{github.run_id}}/runner=2cpu-linux-x64/image=otherimage
```

```yaml
jobs:
  test:
    runs-on: runs-on=${{github.run_id}}/runner=cheap
```

```yaml
jobs:
  test:
    runs-on: runs-on=${{github.run_id}}/runner=fast
```

--------------------------------

### Windows workflow example

Source: https://runs-on.com/docs/runners/platforms

Complete Windows workflow example using the runs-on action, checking environment variables, reading agent logs, and listing local users.

```yaml
name: Windows


on:
  workflow_dispatch:


jobs:
  default:
    runs-on: runs-on=${{ github.run_id }}/image=windows22-full-x64/family=m8i
    steps:
      - uses: runs-on/action@v2
      - name: Checkout
        uses: actions/checkout@v7
      - name: Check current dir and env variables
        run: |
          dir .
          echo $env:USERNAME
          echo $env:RUNS_ON_RUNNER_NAME
      - name: Logs
        run: |
          Get-Content -Path "C:\runs-on\output.log"
      - name: Users
        run: |
          Get-LocalUser | Format-Table -AutoSize Name,Enabled,PasswordLastSet

```

--------------------------------

### Advanced setup processing error

Source: https://runs-on.com/docs/runners/capabilities/code-scanning

Error message shown when the analyze step fails because default setup is still enabled on the repository. Disable default setup before adding the advanced workflow.

```text
CodeQL analyses from advanced configurations cannot be processed when the default setup is enabled

```

--------------------------------

### Full configuration example

Source: https://runs-on.com/docs/runners/labels

Complete configuration example showing images, runners, and admins. Includes custom AMI selection, burstable families, spot settings, and a preinstall script that runs before the GitHub Actions runner agent.

```yaml
_extends: .github-private


images:
  mycustomimage:
    platform: "linux"
    arch: "x64"
    owner: "099720109477"
    # will take the most recent AMI matching the wildcard pattern
    name: "ubuntu/images/hvm-ssd/ubuntu-jammy-22.04-amd64-server-*"


  otherimage:
    platform: "linux"
    arch: "x64"
    ami: "ami-0abcd159cbfafefgh"


runners:
  cheap:
    # Useful for workflows that do not require a lot of CPU / RAM.
    ram: [2, 4, 8]
    # Burstable instances: t8i for x64, t4g for arm64
    family: ["t8i", "t4g"]
    image: otherimage
    ssh: false
  fast:
    cpu: 32
    volume: 200gb:gp3:750mbs:4000iops
    family: ["c8a", "m8a"]
    spot: false
    # reference custom image defined above
    image: mycustomimage
    preinstall: |
      echo "doing some stuff before the GitHub Actions runner agent is executed..."
      echo "For instance, disabling the host's IPv6 if needed"
      sysctl -w net.ipv6.conf.all.disable_ipv6=1


admins:
  - crohr
  - other-github-user
```

--------------------------------

### Provisioning script to install software

Source: https://runs-on.com/docs/guides/building-custom-ami

This provisioning script installs software on the instance. It is referenced in the Packer build block and should be saved as scripts/provision.sh.

```bash
#!/bin/bash
set -e
apt-get update
apt-get install -y software1 software2

```

--------------------------------

### Install pre-commit

Source: https://runs-on.com/docs/observability/cli

Installs the pre-commit package using pip, which is required to use `roc lint` as a pre-commit hook.

```bash
pip install pre-commit

```

--------------------------------

### Workflow example: ARM64 GPU runner with ubuntu24-gpu-arm64

Source: https://runs-on.com/docs/runners/platforms

Workflow example for ARM64 GPU workloads using the ubuntu24-gpu-arm64 image with a compatible family such as g5g. It displays NVIDIA SMI details and the machine architecture.

```yaml
jobs:
  arm64-gpu:
    runs-on: "runs-on=${{ github.run_id }}/family=g5g.xlarge/image=ubuntu24-gpu-arm64"
    steps:
      - uses: runs-on/action@v2
      - name: Display NVIDIA SMI details
        run: |
          nvidia-smi
          uname -m

```

--------------------------------

### Configure CodeQL default setup with gh api

Source: https://runs-on.com/docs/runners/capabilities/code-scanning

REST API command to configure CodeQL default setup with a labeled runner via the GitHub CLI. Replace <ORG> and <REPO> with your repository details.

```bash
gh api -X PATCH repos/<ORG>/<REPO>/code-scanning/default-setup \
  -f state=configured \
  -f runner_type=labeled \
  -f runner_label='runs-on/fleet=codeql-x64/env=production'
```

--------------------------------

### Install latest roc CLI globally with mise

Source: https://runs-on.com/docs/observability/cli

Install the latest stable CLI as your global default using mise.

```bash
mise use --global 'github:runs-on/cli[bin=roc]@latest'
```

--------------------------------

### Advanced setup CodeQL workflow for Flex

Source: https://runs-on.com/docs/runners/capabilities/code-scanning

Advanced setup CodeQL workflow for Flex. Uses a matrix for javascript-typescript, python, and go, with build modes none, none, and autobuild respectively. The runs-on line selects a Flex runner with 4 CPUs.

```yaml
name: CodeQL


on:
  push:
    branches: [main]
  pull_request:
    branches: [main]
  schedule:
    - cron: "30 4 * * 1"


permissions:
  actions: read
  contents: read
  security-events: write


jobs:
  analyze:
    name: Analyze (${{ matrix.language }})
    runs-on: runs-on=${{ github.run_id }}/runner=4cpu-linux-x64
    strategy:
      fail-fast: false
      matrix:
        include:
          - language: javascript-typescript
            build-mode: none
          - language: python
            build-mode: none
          - language: go
            build-mode: autobuild
    steps:
      - uses: actions/checkout@v5
      - uses: github/codeql-action/init@v4
        with:
          languages: ${{ matrix.language }}
          build-mode: ${{ matrix.build-mode }}
      - uses: github/codeql-action/analyze@v4
        with:
          category: "/language:${{ matrix.language }}"

```

--------------------------------

### Workflow example: GPU runner with NVIDIA SMI and Docker

Source: https://runs-on.com/docs/runners/platforms

Workflow example for GPU runners using the ubuntu24-gpu-x64 image. It displays NVIDIA SMI details, verifies Docker GPU support, and runs a placeholder machine learning script.

```yaml
jobs:
  default:
    runs-on: "runs-on=${{ github.run_id }}/family=g4dn.xlarge/image=ubuntu24-gpu-x64"
    steps:
      - uses: runs-on/action@v2
      - name: Display NVIDIA SMI details
        run: |
          nvidia-smi
          nvidia-smi -L
          nvidia-smi -q -d Memory
      - name: Ensure Docker is available with GPU support
        run: docker run --rm --runtime=nvidia --gpus all ubuntu nvidia-smi
      - name: Execute your machine learning script
        run: echo "Running ML script..."

```

--------------------------------

### Example CloudWatch metrics ASCII chart output

Source: https://runs-on.com/docs/observability/cloudwatch

Example output from the Post Run runs-on/action@v2 step. Shows an ASCII chart of CPU User metrics with statistics (min, avg, max).

```text
📈 Metrics (since 2025-06-30T14:18:56Z):


📊 CPU User:
   100.0 ┤
    87.5 ┤                                        ╭─╮╭───────────╮
    75.0 ┤                                       ╭╯ ╰╯           │
    62.5 ┤                                      ╭╯               ╰╮
    50.0 ┤                                      │                 │
    37.5 ┤                                      │                 ╰╮
    25.0 ┤                                     ╭╯                  │
    12.5 ┤                    ╭─────────╮╭─────╯                   ╰╮
     0.0 ┼────────────────────╯         ╰╯                          ╰
                               CPU User (Percent)
  Stats: min:0.0 avg:29.0 max:93.4 Percent

```

--------------------------------

### Install awslogs CLI

Source: https://runs-on.com/docs/maintenance/troubleshooting

Install the awslogs command-line tool to inspect control-plane logs from CloudWatch.

```bash
pip install awslogs
```

--------------------------------

### Parallel database setup

Source: https://runs-on.com/docs/guides/languages/ruby

Set up all test databases in one command using parallel_tests. This creates and loads the schema for all parallel test databases (test_0, test_1, etc.).

```yaml
- name: Setup databases
  run: bundle exec rake parallel:setup
```

--------------------------------

### Traditional matrix job strategy

Source: https://runs-on.com/docs/guides/languages/ruby

Shows the traditional matrix strategy that splits tests across four separate jobs, each incurring VM boot, bundle install, database setup, and coordination overhead.

```yaml
# ❌ Traditional approach: 4 separate jobs
strategy:
  matrix:
    ci_node_index: [0, 1, 2, 3]
```

--------------------------------

### Install git hook scripts

Source: https://runs-on.com/docs/observability/cli

Installs the git hook scripts for pre-commit, enabling `roc lint` to run automatically on staged runs-on.yml files before each commit.

```bash
pre-commit install

```

--------------------------------

### Sticky label example

Source: https://runs-on.com/docs/runners/labels

Use the sticky label to attach a persistent EBS cache disk to a job. The example uses a named lineage 'build-cache' with a 30GB disk.

```yaml
jobs:
  build:
    runs-on: runs-on=${{ github.run_id }}/runner=2cpu-linux-x64/sticky=build-cache:30gb

```

--------------------------------

### Persist toolchains with sticky_cache: tool-cache

Source: https://runs-on.com/docs/runners/capabilities/sticky-disks

Use this mode to keep toolchains downloaded by setup actions (e.g., actions/setup-go) on the sticky disk. Run it before the setup actions. Note that the sticky directory replaces the image's tool cache, hiding preinstalled toolchains, so use this only for toolchains not shipped with the image.

```yaml
steps:
  - uses: runs-on/action@v2
    with:
      sticky_cache: tool-cache
  - uses: actions/setup-go@v7
    with:
      go-version: '1.25.1'

```

--------------------------------

### roc lint examples

Source: https://runs-on.com/docs/observability/cli

Examples of using `roc lint` to lint a specific file, recursively lint all runs-on.yml files, read from stdin, and output in JSON or SARIF formats.

```bash
# Lint a specific configuration file
roc lint .github/runs-on.yml


# Lint all runs-on.yml files recursively (no arguments)
roc lint


# Lint from stdin
cat runs-on.yml | roc lint --stdin


# Lint with JSON output for CI/CD pipelines
roc lint config/runs-on.yml --format json


# Lint with SARIF output for GitHub Code Scanning
roc lint .github/runs-on.yml --format sarif

```

--------------------------------

### Default setup rejection error on Flex

Source: https://runs-on.com/docs/runners/capabilities/code-scanning

Error message shown by GitHub when trying to enable default setup on a Flex runner. Flex registers a just-in-time runner only when a job arrives, so the label is not present when the setting is saved.

```text
Code scanning default setup can only be enabled if a runner with the specified label is assigned to this repository.

```

--------------------------------

### User data script to start SSH

Source: https://runs-on.com/docs/guides/building-custom-ami

This user data script is required to start the SSH daemon so Packer can connect to the instance for provisioning. It should be saved as scripts/user_data.sh.

```bash
#!/bin/bash
systemctl start ssh

```

--------------------------------

### Configure copilot-setup-steps job for GitHub Copilot coding agent on RunsOn

Source: https://runs-on.com/docs/runners/capabilities/ai-agents

Define a copilot-setup-steps job in .github/workflows/copilot-setup-steps.yml that runs on a RunsOn runner before the Copilot coding agent starts. The job uses runs-on/action@v2 and actions/checkout@v7, and you can add steps to preinstall languages, tools, and dependencies. Requires an organization admin to enable repository-level runner customization and configure the allowed runner group/label in Copilot settings, and Copilot's native firewall must be disabled for self-hosted runners.

```yaml
jobs:
  copilot-setup-steps:
    runs-on: runs-on=${{ github.run_id }}/runner=2cpu-linux-x64
    steps:
      - uses: runs-on/action@v2
      - uses: actions/checkout@v7
      # install the languages, tools, and dependencies the agent needs preinstalled
```

--------------------------------

### Custom AMI workflow with runs-on

Source: https://runs-on.com/docs/guides/languages/ruby

Use a custom AMI with pre-installed Ruby and gems to skip ruby/setup-ruby and save 30-60s per job. The image parameter points to your custom AMI, and the workflow runs bundle install only to check for new gems.

```yaml
runs-on: runs-on=${{ github.run_id }}/image=my-ruby-33-rails/family=r8/cpu=16/extras=s3-cache
steps:
  - uses: runs-on/action@v2
  - uses: actions/checkout@v7
  - run: bundle install --jobs 4  # Just checking for new gems
  - run: bundle exec rspec

```

--------------------------------

### nested-virt label example

Source: https://runs-on.com/docs/runners/labels

Shows how to enable nested virtualization on the selected EC2 launch template using the nested-virt label. Requires a RunsOn stack deployment that includes nested launch templates.

```yaml
jobs:
  test:
    runs-on: runs-on=${{github.run_id}}/family=c8i+m8i+r8i/cpu=2+4/nested-virt/image=windows25-full-x64
```

--------------------------------

### Disk label example (deprecated)

Source: https://runs-on.com/docs/runners/labels

Legacy disk label example. In v3, the disk label is parsed but ignored and emits a deprecation warning. Use volume instead.

```yaml
jobs:
  test:
    runs-on: runs-on=${{github.run_id}}/runner=2cpu-linux-x64/disk=large  # deprecated

```

--------------------------------

### Fleet runs-on line for advanced setup

Source: https://runs-on.com/docs/runners/capabilities/code-scanning

The only change needed for Fleet: replace the runs-on line in the advanced setup workflow with this Fleet-specific runner label.

```yaml
    runs-on: runs-on/fleet=codeql-x64/env=production

```

--------------------------------

### Workflow using EFS with sample df output

Source: https://runs-on.com/docs/runners/capabilities/shared-volumes

Example workflow that uses EFS and includes a commented sample output from `df -ah` showing the mount. The comment is part of the displayed code block.

```yaml
jobs:
  efs:
    runs-on: runs-on=${{ github.run_id }}/runner=2cpu-linux-x64/extras=efs
    steps:
      - uses: runs-on/action@v2
      - run: echo "Hello, world!" > /mnt/efs/hello.txt
      - run: cat /mnt/efs/hello.txt
      - run: df -ah /mnt/efs
      # 127.0.0.1:/      8.0E   35G  8.0E   1% /mnt/efs
```

--------------------------------

### RunsOn `_extends` example

Source: https://runs-on.com/docs/runners/labels

Example of inheriting from a global configuration file in the `.github-private` repository. The Flex stack setting `RunnerConfigAutoExtendsFrom` (Terraform: `runner_config_auto_extends_from`) replaces any `_extends` value and defaults to `.github-private`.

```yaml
_extends: .github-private


runners:
  ...

```

--------------------------------

### cpu label example with range

Source: https://runs-on.com/docs/runners/labels

Shows how to request a range of vCPUs using the cpu label. Setting multiple values (e.g., 2+8) allows RunsOn to select any instance with vCPUs between the lowest and highest values.

```yaml
jobs:
  test:
    runs-on: runs-on=${{github.run_id}}/family=m8+c8+r8/cpu=2+8/image=ubuntu22-full-x64
```

--------------------------------

### Full example workflow with StepSecurity images

Source: https://runs-on.com/docs/integrations/stepsecurity

A complete GitHub Actions workflow with three jobs (test-host-outbound, test-docker-outbound, test-docker-build-outbound) that use StepSecurity images and the step-security/harden-runner action to audit or block egress. Each job runs outbound calls from the host, inside a Docker container, or during a Docker build.

```yaml
name: RunsOn Tests


on:
  workflow_dispatch:


jobs:
  test-host-outbound:
    runs-on:
      - runs-on=${{ github.run_id }}
      - runner=2cpu-linux-x64
      - image=ubuntu24-stepsecurity-x64
    steps:
      - name: Harden Runner
        uses: step-security/harden-runner@rc
        with:
          egress-policy: audit
          allowed-endpoints: >
            github.com:443
            goreleaser.com:443


      - uses: runs-on/action@v2


      - name: Checkout code
        uses: actions/checkout@v7


      - name: Run outbound calls from host
        run: |
          start_time=$(date +%s)
          end_time=$((start_time + 90))  # 5 minutes = 300 seconds


          while [ $(date +%s) -lt $end_time ]; do
            curl -I https://www.google.com
            curl -I https://goreleaser.com
            sleep 10  # wait 10 seconds between calls
          done


  test-docker-outbound:
    runs-on:
      - runs-on=${{ github.run_id }}
      - runner=2cpu-linux-x64
      - image=ubuntu24-stepsecurity-x64
    steps:
      - name: Harden Runner
        uses: step-security/harden-runner@rc
        with:
          egress-policy: block
          allowed-endpoints: >
            archive.ubuntu.com:80
            github.com:443
            goreleaser.com:443
            production.cloudflare.docker.com:443
            docker-images-prod.6aa30f8b08e16409b46e0173d6de2f56.r2.cloudflarestorage.com:443
            *.docker.io:443
            security.ubuntu.com:80


      - uses: runs-on/action@v2


      - name: Checkout code
        uses: actions/checkout@v7


      - name: Run outbound calls from within Docker container
        continue-on-error: true
        run: |
          # Start the container
          docker run --rm -d --name test-container ubuntu:latest sleep 90


          # Install curl in the container
          docker exec test-container apt-get update
          docker exec test-container apt-get install -y curl


          # Print /etc/resolv.conf from the container
          docker exec test-container cat /etc/resolv.conf


          # Make outbound calls
          for i in {1..9}; do
            docker exec test-container curl -I https://www.google.com
            docker exec test-container curl -I https://goreleaser.com
            sleep 10  # wait 10 seconds between calls
          done


          # Stop the container
          docker stop test-container




  test-docker-build-outbound:
    runs-on:
      - runs-on=${{ github.run_id }}
      - runner=2cpu-linux-x64
      - image=ubuntu24-stepsecurity-x64
    steps:
      - name: Harden Runner
        uses: step-security/harden-runner@rc
        with:
          egress-policy: audit
          allowed-endpoints: >
            archive.ubuntu.com:80
            auth.docker.io:443
            github.com:443
            goreleaser.com:443
            production.cloudflare.docker.com:443
            docker-images-prod.6aa30f8b08e16409b46e0173d6de2f56.r2.cloudflarestorage.com:443
            registry-1.docker.io:443
            security.ubuntu.com:80


      - uses: runs-on/action@v2


      - name: Checkout code
        uses: actions/checkout@v7


      - name: Build Docker image and test outbound calls during build
        continue-on-error: true
        run: |
          # Create a Dockerfile that installs curl and makes outbound calls
          cat <<EOF > Dockerfile
          FROM ubuntu:latest
          RUN apt-get update && apt-get install -y curl
          RUN for i in {1..9}; do curl -I https://www.google.com && curl -I https://goreleaser.com; sleep 10; done
          EOF


          # Build the Docker image
          docker build -t test-image .


          # Print /etc/resolv.conf from the build container (temporary container used during build)
          container_id=$(docker create test-image)
          docker start $container_id
          docker exec $container_id cat /etc/resolv.conf
          docker stop $container_id
          docker rm $container_id

```

--------------------------------

### ram label example with range

Source: https://runs-on.com/docs/runners/labels

Shows how to request a range of memory using the ram label. Setting multiple values (e.g., 16+64) allows RunsOn to select any instance with RAM between the lowest and highest values.

```yaml
jobs:
  test:
    runs-on: runs-on=${{github.run_id}}/family=m8+c8/ram=16/image=ubuntu22-full-x64
```

--------------------------------

### image label example with arm64

Source: https://runs-on.com/docs/runners/labels

Shows how to specify a custom runner image using the image label. This is useful when you want to use a custom image or don't want to specify a runner label (in which case family is required).

```yaml
jobs:
  test:
    runs-on: runs-on=${{github.run_id}}/family=m8+c8/cpu=2/image=ubuntu22-full-arm64
```

--------------------------------

### Volume label example

Source: https://runs-on.com/docs/runners/labels

Use the volume label to configure a custom EBS volume with size, type, throughput, and IOPS. The example shows a 100GB gp3 volume with 500 MiB/s throughput and 4000 IOPS.

```yaml
jobs:
  test:
    runs-on: runs-on=${{github.run_id}}/runner=2cpu-linux-x64/volume=80gb:gp3:500mbs:4000iops

```

--------------------------------

### Flex troubleshooting commands with roc logs, connect, interrupt

Source: https://runs-on.com/docs/observability/cli

Use these commands for Flex troubleshooting. Start with `logs` to stream console logs, then `connect` for a live SSM shell, and `interrupt` to test Spot interruption handling. Requires AWS credentials that can read RunsOn stack resources.

```bash
JOB_URL="https://github.com/acme/app/actions/runs/123456789/job/987654321"


AWS_PROFILE=runs-on-admin roc logs "$JOB_URL" --include=console --watch
AWS_PROFILE=runs-on-admin roc connect "$JOB_URL"
AWS_PROFILE=runs-on-admin roc interrupt "$JOB_URL" --wait
```

--------------------------------

### Flex job label with local NVMe instance type

Source: https://runs-on.com/docs/runners/capabilities/local-storage-nvme

Configure a Flex job label to use an instance type with local NVMe storage. The example uses `i7ie.2xlarge` for both Linux and Windows jobs, and includes steps to verify the ephemeral storage with `df` or `Get-Volume`.

```yaml
jobs:
  linux-build:
    runs-on: runs-on=${{ github.run_id }}/family=i7ie.2xlarge/image=ubuntu24-full-x64
    steps:
      - uses: runs-on/action@v2
      - uses: actions/checkout@v7
      - run: |
          df -h /mnt/ephemeral
          df -h "$GITHUB_WORKSPACE"


  windows-build:
    runs-on: runs-on=${{ github.run_id }}/family=i7ie.2xlarge/image=windows25-full-x64
    steps:
      - uses: runs-on/action@v2
      - uses: actions/checkout@v7
      - shell: pwsh
        run: |
          Get-Volume -FileSystemLabel RunsOnEphemeral
          Get-Item $env:GITHUB_WORKSPACE
```

--------------------------------

### Fleet runner catalog with local NVMe instance types

Source: https://runs-on.com/docs/runners/capabilities/local-storage-nvme

Pin local-storage instance types in the Fleet runner catalog. The example defines `linux-nvme` and `windows-nvme` runners using `i7ie.2xlarge` with the respective images.

```hcl
runners = {
  linux-nvme = {
    family = ["i7ie.2xlarge"]
    image  = "ubuntu24-full-x64"
  }


  windows-nvme = {
    family = ["i7ie.2xlarge"]
    image  = "windows25-full-x64"
  }
}
```

--------------------------------

### Connect to runner via AWS CLI SSM

Source: https://runs-on.com/docs/runners/capabilities/remote-access

Starts an SSM session to a runner instance using the AWS CLI. Requires an AWS profile with permissions to access the SSM service.

```bash
# AWS CLI
aws ssm start-session --target <RUNNER_INSTANCE_ID>
```

--------------------------------

### roc stack logs usage and examples

Source: https://runs-on.com/docs/observability/cli

Stream all RunsOn application logs from CloudWatch log streams, not filtered by specific jobs. Use this to monitor overall service activity and troubleshoot system-wide issues. The examples show default streaming (last 2 hours), custom since duration, watch mode with default 5s interval, custom watch interval, and short format without color.

```text
Usage:
  roc stack logs [flags]


Flags:
  -f, --format string         Output format: long (default) or short (default "long")
  -h, --help                  help for logs
      --no-color              Disable color output for streamed logs (also off when stdout is not a terminal or NO_COLOR is set)
  -s, --since string          Show logs since duration (e.g. 30m, 2h) (default "2h")
  -w, --watch string[="5s"]   Watch for new logs with optional interval (e.g. --watch 2s)


Global Flags:
  -d, --debug          Enable debug output
      --stack string   CloudFormation stack name (default "runs-on")

```

```bash
# Stream last 2 hours of application logs (default)
AWS_PROFILE=runs-on-admin roc stack logs


# Stream last 24 hours of logs
AWS_PROFILE=runs-on-admin roc stack logs --since 24h


# Stream logs with watch mode (refreshes every 5 seconds)
AWS_PROFILE=runs-on-admin roc stack logs --watch


# Stream logs with custom watch interval
AWS_PROFILE=runs-on-admin roc stack logs --watch 10s


# Stream logs in short format without color
AWS_PROFILE=runs-on-admin roc stack logs --format short --no-color

```

--------------------------------

### Fully custom Linux runner with private subnet

Source: https://runs-on.com/docs/runners/platforms

Launch a fully custom Linux runner with 8 GB RAM, multiple instance families, a specific image, spot disabled, SSH disabled, and a private subnet with static egress IP. This example combines several labels in one runs-on value.

```yaml
jobs:
  build:
    runs-on: runs-on=${{ github.run_id }}/ram=8/family=m8+c8+r8/image=ubuntu24-full-x64/spot=false/ssh=false/private=true
```

--------------------------------

### Combine multiple extras in runs-on label

Source: https://runs-on.com/docs/runners/labels

Combines multiple extras in the runs-on label by joining them with plus signs. This example enables s3-cache, ecr-cache, ecr-pull-through, tmpfs, efs, and otel for a Linux runner.

```yaml
jobs:
  test:
    runs-on: runs-on=${{github.run_id}}/runner=2cpu-linux-x64/extras=s3-cache+ecr-cache+ecr-pull-through+tmpfs+efs+otel

```

--------------------------------

### Enable tmpfs on Fleet runner

Source: https://runs-on.com/docs/runners/capabilities/yolo-mode

Publish a Fleet runner with tmpfs enabled by adding extras = ["tmpfs"] to the runner configuration. This example uses an r8g family instance with 8 CPUs and 16 GiB RAM.

```hcl
runners = {
  linux-tmpfs = {
    cpu    = 8
    ram    = 16
    family = ["r8g"]
    image  = "ubuntu24-full-arm64"
    extras = ["tmpfs"]
  }
}
```

--------------------------------

### GitHub Actions workflow to lint runs-on.yml

Source: https://runs-on.com/docs/observability/cli

Example workflow that lints the RunsOn configuration file on pull requests. It checks out the repository, uses the runs-on/cli action, and runs `roc lint` on the config file.

```yaml
name: Lint RunsOn Config


on:
  pull_request:
    paths:
      - '.github/runs-on.yml'


jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7


      - uses: runs-on/cli@main


      - name: Lint runs-on.yml
        run: roc lint .github/runs-on.yml
```

--------------------------------

### Inherit global configuration with _extends

Source: https://runs-on.com/docs/runners/labels

The first block shows the _extends directive that inherits from a global configuration file, typically stored in the .github-private repository. The second block is an example of a local configuration that uses this directive to inherit global settings.

```yaml
_extends: .github-private
```

```yaml
runners:
  cheap-arm64:
    cpu: [1, 2]
    family: ["t4g"]
    image: ubuntu22-full-arm64
```

--------------------------------

### Magic Cache with type=gha and extras=s3-cache

Source: https://runs-on.com/docs/performance/caching/docker

Use this GitHub Actions workflow to enable the Magic Cache on a RunsOn runner. The `extras=s3-cache` extra transparently redirects the `type=gha` Buildx exporter to S3, requiring no extra configuration. The example sets `cache-to` and `cache-from` to `type=gha,mode=max`.

```yaml
jobs:
  docker:
    runs-on: runs-on=${{ github.run_id }}/runner=2cpu-linux-x64/extras=s3-cache
    steps:
      - uses: runs-on/action@v2
      - uses: actions/checkout@v7
      - uses: docker/setup-buildx-action@v3
      - uses: docker/build-push-action@v4
        with:
          context: "."
          push: false
          tags: test
          cache-to: type=gha,mode=max
          cache-from: type=gha
```

--------------------------------

### Enable SSH for Flex runner in workflow

Source: https://runs-on.com/docs/runners/capabilities/remote-access

Example workflow job that enables SSH for a Flex runner using the ssh=true label. SSH access is allowed by default but the daemon does not start unless the label is set.

```yaml
job: Test
  runs-on: runs-on=${{ github.run_id }}/runner=2cpu-linux-x64/ssh=true
```

--------------------------------

### Follow instance output.log with ddd helper

Source: https://runs-on.com/docs/maintenance/troubleshooting

On the instance, run the ddd helper to print the full log file /runs-on/output.log, or use ddd -f to follow it. This file contains cloud-init boot output, bootstrap script, RunsOn agent, GitHub runner, and local OpenTelemetry collector logs.

```bash
ddd -f
```

--------------------------------

### Complete Rails CI workflow with runs-on

Source: https://runs-on.com/docs/guides/languages/ruby

Production-ready Rails CI workflow using runs-on with postgres and redis services, parallel test setup, and artifact upload. It enables YJIT, caches bootsnap, and uses ruby/setup-ruby with bundler-cache.

```yaml
name: CI


on:
  push:
    branches: [main]
  pull_request:


jobs:
  test:
    runs-on: runs-on=${{ github.run_id }}/family=r8/cpu=16/extras=s3-cache
    services:
      postgres:
        image: postgres:16
        env:
          POSTGRES_PASSWORD: postgres
        options: >-
          --health-cmd pg_isready
          --health-interval 5s
          --health-timeout 3s
          --health-retries 10
          --mount type=tmpfs,destination=/var/lib/postgresql/data
      redis:
        image: redis:7
        options: >-
          --health-cmd "redis-cli ping"
          --health-interval 5s
          --health-timeout 3s
          --health-retries 10
    env:
      DATABASE_URL: postgres://postgres:postgres@postgres:5432/test
      REDIS_URL: redis://redis:6379/0
      RAILS_ENV: test
      RUBY_YJIT_ENABLE: "1"
    steps:
      - uses: runs-on/action@v2
      - uses: actions/checkout@v7


      - uses: ruby/setup-ruby@v1
        with:
          bundler-cache: true


      - uses: actions/cache@v5
        with:
          path: tmp/cache/bootsnap
          key: bootsnap-${{ runner.os }}-${{ hashFiles('Gemfile.lock') }}


      - name: Setup parallel databases
        run: bundle exec rake parallel:setup


      - name: Run tests
        run: bundle exec parallel_rspec spec/ -n 16


      - name: Upload test results
        uses: actions/upload-artifact@v4
        if: always()
        with:
          name: test-results
          path: tmp/rspec-*.xml

```

--------------------------------

### Packer manifest for building arm64 AMI

Source: https://runs-on.com/docs/guides/building-custom-ami

Defines the Packer configuration to build an arm64 AMI. It includes required plugins, variables for subnet, region, and AMI prefix, a data source to find the base AMI, an amazon-ebs source with t4g.small instance type, and a build block with a shell provisioner. The user data file must start SSH so Packer can connect.

```hcl
packer {
  required_plugins {
    amazon = {
      source  = "github.com/hashicorp/amazon"
      version = "~> 1"
    }
  }
}


variable "subnet_id" {
  type    = string
}


variable "region" {
  type    = string
}


variable "ami_prefix" {
  type    = string
}


data "amazon-ami" "runs-on-ami" {
  filters = {
    name                = "runs-on-v2.2-ubuntu22-full-arm64-*"
    root-device-type    = "ebs"
    virtualization-type = "hvm"
  }
  most_recent = true
  owners      = ["135269210855"]
  region      = "${var.region}"
}


source "amazon-ebs" "build-ebs" {
  ami_name      = "${var.ami_prefix}-runs-on-${formatdate("YYYY-MM-DD-hhmmss", timestamp())}"
  instance_type = "t4g.small"
  region        = "${var.region}"
  source_ami    = "${data.amazon-ami.runs-on-ami.id}"
  ssh_username  = "ubuntu"
  subnet_id     = "${var.subnet_id}"
  user_data_file = "./scripts/user_data.sh"
}


build {
  sources = ["source.amazon-ebs.build-ebs"]


  provisioner "shell" {
    execute_command  = "sudo sh -c '{{ .Vars }} {{ .Path }}'"
    script           = "./scripts/provision.sh"
  }
}

```

--------------------------------

### Simplify default spot configuration with wildcards

Source: https://runs-on.com/docs/costs/cost-control

Simplify the default spot configuration using wildcard syntax for instance families. AWS will automatically select the cheapest instance at launch that meets the requirements.

```yaml
runners:
  my-custom-runner:
    spot: lowest-price
    family: ["m8*", "c8*", "r8*", "t8i"]
    ram: [4, 512]
    cpu: [2, 128]

```

--------------------------------

### Initialize and build a custom AMI with Packer

Source: https://runs-on.com/docs/guides/building-custom-ami

Initialize Packer with the custom AMI configuration file, then build the AMI using the specified variables. The build registers a new AMI in your AWS account, which you can reference by ID or name in your workflows.

```bash
packer init custom-ami-arm64.pkr.hcl
```

```bash
packer build -var "ami_prefix=MY_COMPANY" -var "subnet_id=your-subnet-id" -var "region=us-east-1" custom-ami-arm64.pkr.hcl
```

--------------------------------

### Fleet runner label for CodeQL default setup

Source: https://runs-on.com/docs/runners/capabilities/code-scanning

A compound label used to register a Fleet runner scale set for CodeQL default setup. The fleet name and environment must match a fleet in your Fleet configuration.

```text
runs-on/fleet=codeql-x64/env=production
```

--------------------------------

### Flex: Equivalent per-job labels for instance type priority

Source: https://runs-on.com/docs/runners/custom

Shows the equivalent per-job labels for the 'amd-on-demand' and 'amd-spot' runners, using family, image, and spot parameters directly.

```yaml
jobs:
  on-demand:
    runs-on: runs-on=${{ github.run_id }}/family=c8a.large+c8i.large/image=ubuntu24-full-x64/spot=false
  spot:
    runs-on: runs-on=${{ github.run_id }}/family=c8a.large+c8i.large/image=ubuntu24-full-x64/spot=cop

```

--------------------------------

### Scale CPUs: 64cpu runner with race tests

Source: https://runs-on.com/docs/guides/languages/go

Workflow using a single 64-vCPU runner instead of matrix shards, running tests with -race. Go scales well with more cores; predefined runners go up to 64 vCPUs.

```yaml
jobs:
  test:
    runs-on: runs-on=${{ github.run_id }}/runner=64cpu-linux-x64/extras=s3-cache
    steps:
      - uses: runs-on/action@v2
      - uses: actions/checkout@v7
      - uses: actions/setup-go@v5
        with:
          go-version: "1.25"
      - name: Run tests (race)
        run: go test -race ./...
```

--------------------------------

### Configure sticky Docker BuildKit cache with runs-on/action

Source: https://runs-on.com/docs/runners/capabilities/sticky-disks

GitHub Actions workflow that sets up a persistent Docker and BuildKit layer cache on a RunsOn runner. Run after checkout and before docker/setup-buildx-action, using the emitted builder name and inline BuildKit config, with cleanup: false so the RunsOn post step can validate and stop the builder before snapshotting the disk.

```yaml
jobs:
  image:
    runs-on: runs-on=${{ github.run_id }}/runner=2cpu-linux-x64/sticky=docker:30gb
    steps:
      - uses: actions/checkout@v7
      - id: runs-on
        uses: runs-on/action@v2
        with:
          sticky_cache: buildkit
      - uses: docker/setup-buildx-action@bb05f3f5519dd87d3ba754cc423b652a5edd6d2c # v4
        with:
          name: ${{ steps.runs-on.outputs.buildkit-builder }}
          version: v0.34.1
          driver: docker-container
          driver-opts: |
            image=moby/buildkit:v0.31.1
          buildkitd-config-inline: ${{ steps.runs-on.outputs.buildkit-inline-config }}
          cleanup: false
      - uses: docker/build-push-action@v7
        with:
          builder: ${{ steps.runs-on.outputs.buildkit-builder }}
          context: .
          load: true
```

--------------------------------

### ARM64 runner configuration

Source: https://runs-on.com/docs/guides/languages/ruby

Use an ARM64 runner with 16 CPUs and S3 cache. Ruby runs well on ARM64, and Graviton instances are about a quarter cheaper than x64 on-demand.

```yaml
runs-on: runs-on=${{ github.run_id }}/runner=16cpu-linux-arm64/extras=s3-cache
```

--------------------------------

### dpkg lock error output

Source: https://runs-on.com/docs/maintenance/troubleshooting

Example error output when dpkg lock is held by another process, often during apt-get commands.

```text
Run sudo apt-get update -qq && sudo apt-get install build-essential -y
E: Could not get lock /var/lib/dpkg/lock-frontend. It is held by process 1674 (dpkg)
E: Unable to acquire the dpkg frontend lock (/var/lib/dpkg/lock-frontend), is another process using it?
Error: Process completed with exit code 100.
```

--------------------------------

### Request sticky disk and map cache directories with runs-on/action@v2

Source: https://runs-on.com/docs/runners/capabilities/sticky-disks

Workflow requesting a 30GB sticky disk named build-cache on a 2cpu-linux-x64 runner and mapping cache directories (go, pnpm, and custom paths) onto it via runs-on/action@v2. Requires RunsOn v3.2.0+ and the latest runs-on/action@v2; a sticky= label is mandatory when sticky_cache is declared, otherwise the action fails.

```yaml
jobs:
  build:
    runs-on: runs-on=${{ github.run_id }}/runner=2cpu-linux-x64/sticky=build-cache:30gb
    steps:
      - uses: actions/checkout@v7
      - id: sticky
        uses: runs-on/action@v2
        with:
          sticky_cache: |
            go
            pnpm
            custom,path=.turbo,path=vendor/cache
      - if: steps.sticky.outputs.cache-hit != 'true'
        run: echo "At least one cache starts cold"
```

--------------------------------

### apt lock error output

Source: https://runs-on.com/docs/maintenance/troubleshooting

Example error output when apt or dpkg lock is held by another process, such as python or dpkg.

```text
E: Could not get lock /var/lib/apt/lists/lock. It is held by process 1166 (python)
E: Unable to lock directory /var/lib/apt/lists/
```

--------------------------------

### Fleet Terraform: public subnets configuration

Source: https://runs-on.com/docs/control-plane/networking

Minimal Fleet Terraform configuration using public subnets for the smallest installation surface.

```hcl
vpc_id            = var.vpc_id
public_subnet_ids = var.public_subnet_ids

```

--------------------------------

### Downgrade module version

Source: https://runs-on.com/docs/maintenance/upgrades

Downgrade example for Terraform/OpenTofu-managed deployments. Pin the module version to an older release and re-apply; no special procedure is required.

```hcl
module "runs_on_fleet" {
  source  = "runs-on/runs-on/aws//modules/fleet"
  version = "v3.0.0" # the older version you want to roll back to
```

--------------------------------

### Restrict Linux job to compute-optimized families

Source: https://runs-on.com/docs/runners/platforms

Restrict the job to 4-CPU instances from compute-optimized families by using the family=c8 label. This example uses the predefined 4cpu-linux-x64 runner.

```yaml
jobs:
  build:
    runs-on: runs-on=${{ github.run_id }}/runner=4cpu-linux-x64/family=c8
```

--------------------------------

### Pin roc CLI version with mise

Source: https://runs-on.com/docs/observability/cli

Pin the exact CLI version for each stack so `roc` changes automatically when you enter its project directory. Requires mise installed.

```bash
mise use --pin 'github:runs-on/cli[bin=roc]@3.2.3'
```

--------------------------------

### AMI label example

Source: https://runs-on.com/docs/runners/labels

Use the ami label to specify a custom AMI ID for the runner. The AMI must be valid for the region and accessible to the stack's IAM role.

```yaml
jobs:
  test:
    runs-on:
      - runs-on=${{github.run_id}}/family=m8+c8/ami=ami-0123456789abcdef0

```

--------------------------------

### Configure Flex runner volume with gp3:30gb:125mbps:3000iops

Source: https://runs-on.com/docs/performance/warm-pools

Use this Flex runner definition to set the baseline storage configuration `gp3:30gb:125mbps:3000iops` for stopped instances, avoiding extra throughput or IOPS provisioning. Stopped instances still incur storage charges for the provisioned volume (here: 30GB).

```yaml
runners:
  efficient-runner:
    volume: gp3:30gb:125mbps:3000iops

```

--------------------------------

### Disable spot pricing for Linux job

Source: https://runs-on.com/docs/runners/platforms

Disable spot pricing for critical jobs by adding the spot=false label to the runs-on value. This example uses the predefined 2cpu-linux-x64 runner.

```yaml
jobs:
  build:
    runs-on: runs-on=${{ github.run_id }}/runner=2cpu-linux-x64/spot=false
```

--------------------------------

### Disable retry for spot instances

Source: https://runs-on.com/docs/runners/labels

Opts out of the retry mechanism for spot instances. The default retry behavior is when-interrupted, which starts GitHub's rerun failed jobs flow at most twice.

```yaml
jobs:
  test:
    runs-on: runs-on=${{github.run_id}}/runner=2cpu-linux-x64/retry=false
```
Tokens:
Raw