Task & Runbook Configuration

A Runbook defines the executable tasks attached to an SLX. Each Runbook references a CodeBundle containing one or more Robot Framework tasks, along with the configuration, secrets, and dependencies needed to run them.

Tasks within a Runbook can run:

On demand — triggered manually from the UI or API
In response to alerts — triggered automatically when an SLI alert fires (via alertConfig)
Via AI Assistants — dispatched by AI Assistants during troubleshooting

Managing Tasks in the UI

Tasks are the most visible SLX component in the RunWhen Platform. They appear in Workspace Studio > Tasks, grouped by platform category (Kubernetes, GCP, etc.) and organized in a resource hierarchy.

Studio Tasks — SLXs grouped by platform, cluster, and namespace with search and filter controls

Expand any SLX to see its individual tasks. Each task corresponds to one Robot Framework test case extracted from the CodeBundle.

SLX expanded — individual tasks within the "Adservice Deployment Health" SLX

Select one or more tasks and click the Run dropdown to execute them. You can choose an AI Assistant persona or run without an assistant.

Run dropdown — select an assistant persona or run tasks directly

The SLX Preview dialog (eye icon) shows the Tasks tab with all tasks in the SLX and their last run time.

SLX Preview — Tasks tab showing all tasks with last run timestamps

The RunSessions tab lists historical executions, the number of issues found per session, and when each session ran.

SLX Preview — RunSessions tab showing execution history with issue counts

When creating a task through the UI, the platform guides you through selecting a CodeBundle, configuring environment variables, mapping secrets, and choosing a runner location — without requiring you to write YAML directly.

Spec Reference

The sections below document the full Runbook Custom Resource spec for users who manage SLX configuration through Git or need to understand the underlying data model.

Runbook Spec Overview

apiVersion: runwhen.com/v1
kind: Runbook
metadata:
  name: my-workspace--my-slx-runbook
  labels:
    workspace: my-workspace
    slx: my-workspace--my-slx
spec:
  codeBundle:
    repoUrl: https://github.com/runwhen-contrib/rw-cli-codecollection
    pathToRobot: codebundles/k8s-namespace-healthcheck/runbook.robot
    ref: main
  location: northamerica-northeast2-01
  lookbackWindow: 30m
  configProvided:
    - name: NAMESPACE
      value: production
    - name: CONTEXT
      valueFrom:
        workspace: CONTEXT
  secretsProvided:
    - name: kubeconfig
      workspaceKey: kubeconfig
  servicesProvided:
    - name: KUBECONFIG
      locationServiceName: kubeconfig.shared
  requirements:
    - pip: requirements.txt

Spec Fields

Field	Type	Description
`codeBundle`	object	Required. Git reference to the Robot Framework file
`location`	string	Runner location where tasks execute (e.g. `northamerica-northeast2-01`)
`lookbackWindow`	string	Time window for lookback queries (pattern: `[0-9]+[smhd]`, e.g. `30m`, `1h`)
`configProvided`	object[]	Environment variables passed to the task
`secretsProvided`	object[]	Workspace secrets mapped into the task
`servicesProvided`	object[]	Location service bindings
`requirements`	object[]	Python/dependency configuration

CodeBundle

The codeBundle field points to the Robot Framework .robot file that contains the tasks:

Field	Required	Description
`repoUrl`	Yes	Git repository URL
`pathToRobot`	Yes	Path to the `.robot` file within the repository
`ref`	Yes	Git ref — branch, tag, or commit (default: `main`)

The .robot file is parsed by the platform to extract individual tasks. Each task becomes independently runnable through the UI, API, or assistant-triggered execution.

Configuration Variables (`configProvided`)

Environment variables injected into the task runtime. Each entry supports a literal value or a reference to workspace/SLX-level configuration:

configProvided:
  - name: NAMESPACE
    value: production
  - name: CONTEXT
    valueFrom:
      workspace: CONTEXT
  - name: LABELS
    valueFrom:
      slx: LABELS

Field	Description
`name`	Variable name (alphanumeric and underscores)
`value`	Static string value
`valueFrom.workspace`	Resolves from workspace-level `configProvided`
`valueFrom.slx`	Resolves from the parent SLX’s `configProvided`

Secrets (`secretsProvided`)

Maps workspace secrets into the task runtime. Secrets are stored securely and referenced by key:

secretsProvided:
  - name: kubeconfig
    workspaceKey: kubeconfig
  - name: gcp_credentials
    workspaceKey: gcp-service-account

Field	Description
`name`	Name used in the Robot Framework file to reference the secret
`workspaceKey`	Key of the secret stored in the workspace

Location Services (`servicesProvided`)

Binds location-level services (like shared kubeconfigs) into the task:

servicesProvided:
  - name: KUBECONFIG
    locationServiceName: kubeconfig.shared

Field	Description
`name`	Name used in the task; also set as an environment variable
`locationServiceName`	Service identifier — use `.shared` suffix for shared services across the location

Requirements

Defines Python dependencies for the CodeBundle:

requirements:
  - pip: requirements.txt
    loadSecondaryDependencies: false

Field	Default	Description
`pip`	`requirements.txt`	Path to pip requirements file in the CodeBundle
`lockFile`	—	Lock file path (e.g. `poetry.lock`)
`pypi`	—	List of additional PyPI packages
`platform`	—	List of platform-specific packages
`loadSecondaryDependencies`	`false`	Whether to install transitive dependencies

Task Resolution

When a Runbook is processed, the platform:

Resolves the CodeBundle to a specific version
Parses the .robot file to extract task names, tags, and documentation
Makes each task available for execution:

status:
  codeBundle:
    tasks:
      - Check Namespace Health
      - List Failing Pods
      - Get Pod Logs
    taskDetails:
      Check Namespace Health:
        tags: "health,namespace"
      List Failing Pods:
        tags: "pods,failing"
      Get Pod Logs:
        tags: "pods,logs"

Each resolved task becomes available for execution through:

Workspace Studio — run tasks manually from the Tasks view
Workspace Chat — assistants discover and run relevant tasks
SLI alert triggers — automatic execution when alertConfig fires
API — programmatic task execution via RunSession creation

Example Configurations

Kubernetes namespace health check

spec:
  codeBundle:
    repoUrl: https://github.com/runwhen-contrib/rw-cli-codecollection
    pathToRobot: codebundles/k8s-namespace-healthcheck/runbook.robot
    ref: main
  location: northamerica-northeast2-01
  configProvided:
    - name: NAMESPACE
      value: production
    - name: CONTEXT
      valueFrom:
        workspace: CONTEXT
  secretsProvided:
    - name: kubeconfig
      workspaceKey: kubeconfig

GCP service diagnostics

spec:
  codeBundle:
    repoUrl: https://github.com/runwhen-contrib/rw-cli-codecollection
    pathToRobot: codebundles/gcp-service-health/runbook.robot
    ref: main
  location: us-central1-01
  configProvided:
    - name: PROJECT_ID
      value: my-gcp-project
    - name: SERVICE_NAME
      value: api-gateway
  secretsProvided:
    - name: gcp_credentials
      workspaceKey: gcp-service-account
  requirements:
    - pip: requirements.txt

Custom task with lookback window

spec:
  codeBundle:
    repoUrl: https://github.com/my-org/my-codecollection
    pathToRobot: codebundles/custom-check/runbook.robot
    ref: v1.2.0
  location: northamerica-northeast2-01
  lookbackWindow: 1h
  configProvided:
    - name: THRESHOLD
      value: "95"
  servicesProvided:
    - name: KUBECONFIG
      locationServiceName: kubeconfig.shared

SLXs (Learn) — conceptual overview of SLXs
Tasks & CodeBundles — how CodeBundles and task execution work
SLI Configuration — SLI metric collection and threshold alerts
SLO Configuration — error budget alerting