> ## Documentation Index
> Fetch the complete documentation index at: https://docs.run.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# CI

> GitHub Checks on Firecracker sandboxes, without GitHub Actions minutes

# CI

Run pull request and push checks on [run.cloud sandboxes](/sandboxes) instead of
GitHub-hosted runners. Results show up as normal GitHub Check Runs
(`run.cloud / <job>`), so you can require them in branch protection.

Jobs boot from any OCI image, run shell steps against the commit SHA, and tear
down when they finish. You keep your workflows under **`.github/workflows/`**
and **opt in** a job with `runs-on: runcloud`.

## Why use it

* **No Actions minutes** for opted-in jobs — compute is billed as sandbox usage
  on your run.cloud org.
* **Same PR UI** — green / red checks on the commit, re-run from the Checks tab.
* **Familiar shape** — stay in `.github/workflows/` with a small, documented
  subset of GitHub Actions syntax.
* **Secrets you already manage** — inject [secret groups](/sandboxes/secrets)
  from your run.cloud org (not the GitHub Actions secrets store).

## Quick path

<Steps>
  <Step title="Connect GitHub">
    In the [dashboard](https://run.cloud/dashboard/settings), open **GitHub CI**
    and install the [Run Cloud CI](https://github.com/apps/run-cloud-ci) GitHub
    App on the repositories you want. That links the installation to your
    run.cloud org so only bound orgs ever run jobs.
  </Step>

  <Step title="Add a workflow">
    Create `.github/workflows/ci.yml` with at least one job that sets
    `runs-on: runcloud`. See [GitHub workflows](/ci/github-workflows) for full
    examples.
  </Step>

  <Step title="Open a pull request">
    Checks named `run.cloud / &lt;job&gt;` appear on the head commit. Require
    them under branch protection when you are ready.
  </Step>
</Steps>

## Minimal example

```yaml theme={null}
# .github/workflows/unit.yml
name: unit

# Prefer workflow_dispatch so GitHub Actions does not also try to schedule this
# file on a self-hosted runner named "runcloud". run.cloud still runs the job
# from the GitHub App on pull_request and push.
on:
  workflow_dispatch:

jobs:
  unit:
    runs-on: runcloud
    container: node:22
    env:
      RUNCLOUD_CPU: "1"
      RUNCLOUD_MEMORY: "2048"
      RUNCLOUD_PATHS: "src/**,package.json,package-lock.json"
    steps:
      - uses: actions/checkout@v4
      - run: npm ci
      - run: npm test
```

| Piece                              | Meaning                                                                                         |
| ---------------------------------- | ----------------------------------------------------------------------------------------------- |
| `runs-on: runcloud`                | **Opt-in**; only these jobs run on run.cloud                                                    |
| `container:`                       | OCI image for the sandbox (for example `node:22`, `golang:1.22`)                                |
| `RUNCLOUD_CPU` / `RUNCLOUD_MEMORY` | vCPU and MiB for the sandbox                                                                    |
| `RUNCLOUD_PATHS`                   | Comma-separated path globs; non-matching PRs get a green **Skipped** check                      |
| `actions/checkout`                 | No-op; run.cloud already checks out the commit SHA                                              |
| `run:` steps                       | Shell commands via `/bin/sh` in the sandbox (portable; works with common images like `node:22`) |

## What runs where

| Job `runs-on`                             | Who executes it                   |
| ----------------------------------------- | --------------------------------- |
| `runcloud` (or `run.cloud` / `run-cloud`) | run.cloud CI on Firecracker       |
| `ubuntu-latest`, other GitHub labels      | Normal GitHub Actions (unchanged) |

You can mix both in the same repository: keep heavy or unsupported Actions jobs
on GitHub, and move simple shell CI to run.cloud.

## Next

* **[GitHub workflows](/ci/github-workflows)** — multi-job examples, path
  filters, monorepos, branch protection.
* **[Secrets in CI](/ci/secrets)** — inject org secret groups and
  `${{ secrets.NAME }}`.
* **[Configuration reference](/ci/configuration)** — supported fields, defaults,
  and the documented subset of GitHub Actions syntax.