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

# GitHub Actions runners

> Configure GitHub Actions runners through the bead GitHub App, select repositories and labels, and inspect jobs and logs.

Use bead GitHub Actions runners to provision a fresh temporary machine for each matching job. GitHub assigns the job; bead bills and deletes the machine for that assignment.

## Connect selected repositories

Create `selection.json` with repositories you control and templates available to your account:

```json theme={null}
{
  "repositories": ["owner/repo"],
  "templates": {"bead": "ci-4x8", "bead-small": "ci-2x4"},
  "concurrency": 10,
  "warm_buffer": 0
}
```

```bash theme={null}
bead ci connect --config selection.json
```

The command opens GitHub installation and authorization, then waits for confirmation. You must have installation-management authority: the installation belongs to you, or you are an active organization administrator. Confirm the bead organization and selected repositories.

Repository runners require Administration write, Actions read and Metadata read permissions. Install the App only on the repositories you want to run.

## Select a runner

```yaml theme={null}
name: Tests
on: [push]
jobs:
  test:
    runs-on: bead
    steps:
      - uses: actions/checkout@v4
      - run: npm ci && npm test
```

| Label | vCPU | Memory |
| - | - | - |
| `bead-small` | 2 | 4 GiB |
| `bead` | 4 | 8 GiB |
| `bead-large` | 8 | 16 GiB |
| `bead-xlarge` | 16 | 32 GiB |

Configure matching template resources for each label. Explicit selectors such as `bead-4x8` and configured custom `bead-<name>` labels are supported. Append `/from=<golden>` to choose a matching saved toolchain, or `/debug` to retain a failed job machine for 30 minutes subject to normal funding.

Each job must request exactly one label beginning with `bead`, and its base selector must have an entry in `selection.json.templates`, including explicit selectors such as `bead-4x8`. Put suffixes such as `/debug` and `/from=TOOLCHAIN` on that same label.

Runner machines are retired when their age reaches six hours. Keep jobs within that lifetime.

## Inspect jobs and logs

```bash theme={null}
bead ci
bead ci repos
bead ci job "$JOB_ID"
bead ci logs "$JOB_ID" --follow
```

Live logs poll a bounded 1 MiB buffer of masked GitHub job pages. Truncation is explicit. Live sampling is best effort; GitHub keeps the authoritative completed logs.

Public repositories are off by default. An administrator can allow selected actors with `bead ci public owner on --users alice,bob`, allow anyone with `--anyone`, or disable access with `bead ci public owner off`. Both the original and triggering actors must be allowed.

`bead ci disconnect "$INSTALLATION_ID"` disables provisioning and retires owned machines. Check [limits](https://docs.bead.run/platform/limits.md) and funded balance before running jobs. For other CI systems, use [portable CI](https://docs.bead.run/ci/portable.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.