# GitHub

GitHub holds your code, runs the build steps (in GitHub Actions, on your quota), and signs you in to the console. Starwisp installs as a **GitHub App** in your own organization.

**Time:** about 5 minutes if you already have an organization. **Needs:** you are an **owner** of a GitHub **organization**. Personal accounts are not supported.

## Steps

1. Create a free organization if you do not have one: <https://github.com/account/organizations/new?plan=free>.
2. Install the GitHub CLI from <https://cli.github.com> and run:

   ```bash
   gh auth login
   gh auth refresh -s repo,workflow,read:org
   ```

3. Run the installer (see [install](../install.md)). It creates the App for you from a prefilled form. You click **Create GitHub App**, then **Install**, and choose **All repositories** (not *Only select repositories*).

**Least privilege:** the installer asks for a short list of permissions and turns the webhook off. The full list and the reason for each is in [security](../security.md). "All repositories" is needed because each app you build gets its own new repository, and the App must see it. With *Only select repositories*, your first run fails when it reaches that new repository. The Setup page row **GitHub App covers all repositories** checks this and links to the fix: `https://github.com/organizations/<org>/settings/installations` → the App → *Repository access* → *All repositories* → Save.

## Where it goes

The installer fills these for you. You do not paste anything.

| What | Where it is stored |
|---|---|
| `APP_ID` (a variable) | `<org>/factory` → Settings → Secrets and variables → Actions → Variables |
| `APP_PRIVATE_KEY` (a secret) | same page, Secrets |
| `APP_WEBHOOK_SECRET` (a secret) | same page, Secrets |
| Sign-in id and secret | Your Cloudflare Worker (`AUTH_GITHUB_ID`, `AUTH_GITHUB_SECRET`) |

In the console they appear as the **GitHub App** card in Settings → Vault (fields **App ID** and **Private key (.pem)**).

**You should now see** `APP_ID` under Variables and `APP_PRIVATE_KEY` under Secrets in `<org>/factory`.

## What it gates

Everything. It creates each app's repository, pushes code, opens pull requests, and signs you in to the console.

## What it costs

A free organization works. Actions minutes on private repos are included up to a monthly allowance on the Free plan (estimated about 2,000 Linux minutes; check GitHub's current billing page). macOS runner minutes cost extra if iOS builds use them. Runs on your own quota are billed by GitHub to you.

## Slow prerequisites

None.

## Common problems

- "The installer says the App is not installed": choose **Install** and **All repositories**, then run `npx starwisp init` again. See [install](../install.md).
- Your organization blocks members from creating private repositories: run the installer as an owner.
- Branch rules that block direct commits to `main` can stop the console from saving settings. Allow the App to push, or tell support.