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

# Quick start

> Connect GitHub, change one line of a workflow, and see your first GitHub Actions job run on an InstaBox machine.

Run a GitHub Actions job on an InstaBox machine in four steps. You need a repository with a
workflow, and an InstaBox account.

**1. Connect GitHub**

On the dashboard's **CI** page, click **Connect GitHub** to install the instabox GitHub App.
You can read what the App asks for under [GitHub App permissions](#github-app-permissions).

![The CI page: Connect GitHub, then change runs-on to instabox-medium](https://mintcdn.com/instacloud/N9PM4qc9k2LHbGZu/images/ci-setup.webp?fit=max\&auto=format\&n=N9PM4qc9k2LHbGZu\&q=85\&s=8ca6ef275693bcfcee35d8eed13e4684)

**2. Change runs-on in your workflow**

In your workflow file, set the job's `runs-on` to an InstaBox label. `instabox-medium` is the
label that every plan can use.

```yaml theme={null}
jobs:
  test:
    runs-on: instabox-medium
```

Each job with this label gets a fresh Ubuntu 24.04 machine that has the tools of GitHub's
`ubuntu-24.04` image, and the machine is deleted when the job ends.

**3. Push the change**

Commit the workflow and push it. GitHub starts the job, and InstaBox gives it a machine.

```bash theme={null}
git commit -am "Run CI on InstaBox" && git push
```

**4. See your jobs**

When a job has to wait or is refused, GitHub shows it only as queued. To see your jobs and the
reason why one waits or was refused, open the dashboard's **CI** page or list the jobs with
the CLI.

```bash theme={null}
instabox ci
```

The list shows your recent jobs with the newest first. Each row has the job's size, its
state, and how long the job waited for a machine and ran.

## GitHub App permissions

> [accordion] What the GitHub App asks for
>
> The [instabox GitHub App](https://github.com/apps/instabox-cloud) asks for these permissions:
>
> | Permission | Used for |
> | - | - |
> | Metadata: read | Required by GitHub for every App |
> | Actions: read | A job's branch, commit, and failed step |
> | Administration: read and write | Registering and deleting each job's runner |
> | Members: read (organizations) | Checking that whoever links an organization belongs to it |
>
> The App asks for nothing on your code, pull requests, issues, or workflows.

> [accordion] Why Administration?
>
> GitHub lets an App add a runner to a repository only through Administration. Personal accounts
> have no organization-level runners, so Administration is the only way to run their CI.

> [accordion] Don't want to grant it?
>
> You can call the CLI from any CI instead, which needs no GitHub App and only an API key, as
> [Run the CLI from any CI](https://instabox.sh/docs/use-cases/ci#run-the-cli-from-any-ci) shows. On Enterprise, we can set up a
> narrower App for your organization: [contact us](https://instabox.sh/contact).

> [card] [Choose a machine size](https://instabox.sh/docs/use-cases/ci#choose-a-machine-size)
>
> The labels for larger machines, and the plans that can use them.

> [card] [Advanced: custom setup](https://instabox.sh/docs/use-cases/ci/custom-setup.md)
>
> Start every job with your toolchain, caches, and images already in place.
