Runnable documentation

Operate CI without the guesswork.

A practical reference for connecting source providers, writing workflows, controlling runs, protecting deployments, managing spend, and giving agents a safe MCP interface.

How Runnable works

Your Git provider remains the source of truth. Runnable turns workflow YAML into an immutable plan, schedules dependency-ready jobs, and executes every job on a clean Linux x64 machine.

Source

GitHub, an Entire mirror, or an Entire-native repository.

Plan

Validated YAML in .runnable/workflows becomes an immutable DAG.

Execute

Each job runs on an isolated Ubuntu 22.04 or 24.04 machine.

Observe

Follow steps, masked logs, artifacts, approvals, and usage.

Runnable is independent CI

GitHub Actions does not parse, schedule, execute, log, cache, or store Runnable jobs. GitHub supplies source, signed events, installation tokens, pull requests, and Check Runs for GitHub-backed repositories.

Quickstart

The normal path from a new organization to a running workflow takes four steps.

1
Create an organization
Sign in, create the workspace that owns repositories and credentials, then confirm the active organization in the dashboard.
2
Connect a provider
Install the GitHub App for selected repositories, register an Entire-native repository, or configure an Entire mirror for GitHub checkout.
3
Add a workflow
From a repository with zero workflows, create a starter pull request, migrate compatible GitHub Actions, or commit YAML under .runnable/workflows/*.yml yourself.
4
Trigger and observe
Push a commit, open a pull request, or manually dispatch a workflow. Open Runs for the job graph and live logs.

Run your first workflow

Runnable intentionally accepts familiar Actions syntax. Start small, verify the compatibility report, then move deployment jobs after the CI path is stable.

.runnable/workflows/ci.ymlYAML

name: CI
on:
  push:
    branches: [main]
  pull_request:

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 24
      - run: npm ci
      - run: npm test

Check before you connect

The public checker classifies a pasted workflow as Full, Partial, Runtime-dependent, or Unsupported.

Check workflow

Choose a guide

The documentation is organized by the task you are trying to complete, with persistent navigation and search on every page.

Write a workflow

Triggers, jobs, matrices, expressions, permissions, caching, artifacts, reusable workflows, and support boundaries.

Read guide

Connect source

Separate, operational setup for GitHub repositories, Entire mirrors, and Entire-native repositories.

Read guide

Operate runs

Dispatch, cancellation, retries, logs, artifacts, environment approvals, and conclusions.

Read guide

Connect an agent

Issue a least-privilege MCP token, configure a client, and use safe read-then-write workflows.

Read guide

Protect delivery

Secret precedence, fork behavior, required reviewers, wait timers, branch rules, and deployment URLs.

Read guide

Administer the service

Plans, normalized minutes, roles, workspace keys, audit events, integrations, and the customer API.

Read guide

For operators

Runs, approvals, logs, billing, and troubleshooting.

For administrators

Providers, scopes, members, credentials, and limits.

For agents

MCP schemas, safe workflows, cursors, and error handling.

NextWorkflow referenceStart with the supported YAML contract.