---
title: "Run workflows on CRACI runners"
description: "Configure GitHub Actions workflow YAML to run jobs on CRACI runners"
source: "https://docs.craci.com/guides/runner-workflows/"
---

CRACI runners are GitHub Actions-compatible: an existing workflow runs on CRACI by changing the job's `runs-on` to `craci`. This guide covers how you can set up your workflow YAML. To get started, you need to already have a CRACI account connected to your GitHub organization or repositories.

## Minimal workflow

```yaml
jobs:
  build:
    runs-on: craci
    steps:
      - uses: cracicorp/setup@v1
        with:
          size: "4"
          image: "default"
      - uses: actions/checkout@v4
      - run: make build
```

:::note
Add `cracicorp/setup@v1` before the job's other steps to configure its resources.
Omit it to use the defaults.
:::

## `runs-on`

Set `runs-on: craci` to send a job to a CRACI runner. The `craci` label is what GitHub uses to queue the job for CRACI. This is the minimum setup. Add the setup step to choose the runner size or image.

See [Runner configuration](/reference/runner-configuration/) for all supported
`cracicorp/setup@v1` inputs and [Runner images](/reference/runner-images/) for the
available image names.

## Malformed inputs

A malformed resource input such as a non-numeric `size` discards the whole setup
step: the job runs on the built-in default template and CRACI reports a warning on
the job. An unknown image name is rejected instead of running with a different
image.

## Migrate with an AI agent

If you use a coding agent (Claude Code, Codex, Cursor, or similar), it can do the
migration for you. Give it this prompt:

```text
Migrate my GitHub Actions workflows to CRACI runners. Follow the guide at https://docs.craci.com/skills/craci/SKILL.md
```

The agent reads your repository's workflows, proposes a per-job migration plan,
and changes runner routing without touching build logic.

Your GitHub connection must already be in place before the agent can queue jobs
on CRACI runners. See [Connect your GitHub organization](/guides/github-connection/).