This repository contains the schema definition and validation tools for runs-on.yml configuration files used by RunsOn.
The RunsOn config schema defines the structure and validation rules for repository configuration files. This module provides:
- CUE Schema: Authoritative schema definition in CUE format (
schema/runs_on.cue) - JSON Schema: Generated JSON schema for tooling integration (
schema/schema.json) - Go Validation Library: Go package for validating config files (
pkg/validate) - CLI Linter: Standalone binary for linting config files (
cmd/lint)
- mise (formerly rtx) - for managing tool versions
- Go 1.23+ (installed via mise)
# Install dependencies
make setup
# Or manually:
mise install
mise exec -- go install cuelang.org/go/cmd/cue@latestgo get github.com/runs-on/configgo install github.com/runs-on/config/cmd/lint@latestimport (
"context"
"github.com/runs-on/config/pkg/validate"
)
diagnostics, err := validate.ValidateFile(ctx, "path/to/runs-on.yml")
if err != nil {
// handle error
}
for _, diag := range diagnostics {
fmt.Printf("%s:%d:%d: %s\n", diag.Path, diag.Line, diag.Column, diag.Message)
}# Validate a file
lint path/to/runs-on.yml
# Read from stdin
cat runs-on.yml | lint --stdin
# JSON output
lint --format json path/to/runs-on.yml
# SARIF output (for GitHub Actions)
lint --format sarif path/to/runs-on.ymlThe roc CLI includes a lint command:
roc lint path/to/runs-on.yml
roc lint --format json path/to/runs-on.yml
roc lint --stdin < runs-on.yml
roc lint # will find config files in current treeThe runs-on.yml file supports:
_extends: Reference to another repository's config (string)runners: Map of runner specificationsimages: Map of image specificationspools: Map of pool specificationsadmins: List of admin usernames (array of strings)
Custom top-level attributes are also supported, for example for use with YAML anchors. However they should be prefixed with x- or some other prefix, as to not conflict with future top-level attributes of RunsOn.
runners:
my-runner:
cpu: [2, 4] # CPU count(s) - int, string, or array
ram: [16, 32] # RAM in GB - int, string, or array
family: [c7a, m7a] # Instance family
image: ubuntu22-full-x64
spot: "pco" # Spot configuration
ssh: false # SSH access (bool or string)
private: true # Private network (bool or string)
volume: "80gb:gp3:125mbs:3000iops" # Volume spec
extras: ["s3-cache"] # Extra features
tags: ["Team:DevOps"] # Tagsimages:
ubuntu22-custom:
ami: ami-1234567890abcdef0
platform: linux
arch: x64
name: ubuntu-22.04
owner: 123456789012
preinstall: |
apt-get update
apt-get install -y dockerpools:
dependabot:
name: dependabot
env: production
timezone: UTC
runner: small-x64
max_surge: 5
schedule:
- name: default
hot: 2
stopped: 3
- name: nights
hot: 0
stopped: 1
match:
day: [monday, tuesday]
time: ["22:00", "06:00"]The validator fully supports YAML anchors and aliases:
runners:
base-runner: &base
cpu: [2]
ram: [16]
family: [c7a]
extended-runner:
<<: *base
cpu: [4]- Edit
schema/runs_on.cue - Run
make gento regenerateschema/schema.json - Run
make testto verify changes - Commit both
.cueand.jsonfiles
make testmake lintmake install
# or
go install ./cmd/lintAdd this to your workflow:
- name: Validate runs-on.yml
uses: docker://ghcr.io/runs-on/config-lint:latest
with:
args: .github/runs-on.ymlOr use the binary:
- name: Install linter
run: go install github.com/runs-on/config/cmd/lint@latest
- name: Validate config
run: lint .github/runs-on.ymlAdd to .pre-commit-config.yaml:
repos:
- repo: https://github.com/runs-on/config
rev: v0.1.0
hooks:
- id: lint
args: [--format, json]MIT