GitHub Actions

Run your GitHub Actions jobs on sandboxes by changing one line of a workflow.

Connect GitHub#

In the console, Settings → GitHub, choose **Connect GitHub**. GitHub asks where to install the agental runs-on App and which repositories it may use, then asks you to sign in to GitHub, so that agental knows the installation is yours. An owner or an admin of the organization connects it, and the organization pays for the sandboxes its jobs run on.

Ask for a sandbox#

Change runs-on in a workflow to a sandbox size:

jobs:
  test:
    runs-on: agental-medium
    steps:
      - uses: actions/checkout@v4
      - run: npm ci && npm test

Or ask for plain runs-on: agental: the job gets the size of the template set for its repository's pool (see below), or medium where none is set. Change the template's size and the jobs after it get the new size. self-hosted, linux and x64 may stand beside the label. A job that asks for any other label is not taken.

What a job gets#

• A whole virtual machine of its own, with root through sudo, Docker, and the tools a sandbox has. The job runs as the user runner, as on GitHub's own runners.
• Each repository has a pool of sandboxes of each size, kept stopped between jobs. A job finds the disk the last one left: dependencies, Docker layers and build output, with no cache step.
• A job of a pull request from a fork runs on a sandbox of its own, deleted when it ends, and a pool sandbox that ever ran a fork's code is deleted too: nothing a stranger's code left is on a disk a later job trusts.
• Sandboxes are made, started and stopped as any other, and billed by the second while they run.

A repository's pool#

Each repository's pool keeps up to a set number of sandboxes of each size, made on the empty runs-on template. Change either in the console, Settings → GitHub, under Pools, or with agental ci set acme/app --pool 2 --template ci-secrets, setRunsOnRepository in TypeScript, or set_runs_on_repository in Python. A template gives the pool's jobs its variables and files, such as a registry token, only where GitHub says the repository is private and runs no workflows from fork pull requests: GitHub may give a fork's job any idle runner, so every other pool, and a fork's own sandbox, is made on the empty template. A pool sandbox made on another template than its pool's now is made again before its next job. Jobs that ask for plain agental take the template's size (a new template has your default template's), wherever the repository is: one of another size sends them to the pool of that size, and the sandboxes of the old size stay for jobs that ask for it by name until you delete them. Sandboxes made from then on take the change; agental ci reset acme/app goes back to the defaults.

What CI costs#

On the console's Usage page, **Made by** lists **GitHub Actions** beside your keys: tick it alone to see what your CI jobs' sandboxes ran up, the deleted ones of forks included. GET /v1/usage?apiKeyId=runs-on gives the same. Each of these sandboxes is tagged ci, with its repository as the metadata agental.github-repository, so GET /v1/sandboxes?tag=ci lists those there are now.

Disconnect#

**Disconnect** on the same page, or uninstalling the App on GitHub, stops agental taking that installation's jobs. They wait on GitHub until another runner takes them. The pool's sandboxes are kept, stopped, until you delete them.

The full machine-readable reference is OpenAPI 3.1. Every page as Markdown, for an agent: llms.txt. Questions: [email protected]