# GitHub

> Connect GitHub for the Coder: which token to create, the exact permissions for each step, where to paste it, and how to fix the usual errors.

GitHub is where most Coders do their work. Connect it and the Coder reads your repositories, issues, and pull requests, copies the repository into its own [workspace](/docs/workspaces/files), and turns finished work into a pull request you can review. When your [house rules](/docs/ceo/house-rules) allow it, it can also merge, and the CEO can have a new private repository made for a Coder.

> [!IMPORTANT]
> Today you connect GitHub in the **StellarFirm desktop app**. On stellarfirm.ai you can browse [Integrations](https://stellarfirm.ai/app/integrations) and read what each tool does; connecting from the web is Coming soon.

## At a glance

| | |
| --- | --- |
| Category | Source control |
| Status | Available |
| Used by | Coder (available now), Product owner and Support (Coming soon) |
| Connect in | The StellarFirm desktop app, under Integrations |
| What you paste | One personal access token |
| Works with | github.com repositories, personal or in an organization |

## What assistants can do

Each step needs a permission on the token. The table shows which one, so you can give exactly what you want and no more.

| Ability | How it runs | Fine-grained token permission | Classic token scope |
| --- | --- | --- | --- |
| Read repositories, issues, and pull requests | Reads on its own | Metadata: Read, Issues: Read, Pull requests: Read | `repo` |
| Read the changed files of a pull request | Reads on its own | Pull requests: Read | `repo` |
| Read check results | Reads on its own | Commit statuses: Read (see the note below) | `repo` |
| Copy the repository into its workspace | Reads on its own | Contents: Read | `repo` |
| Open an issue | Waits for your Approve | Issues: Read and write | `repo` |
| Push a branch with its work | Waits for your Approve | Contents: Read and write | `repo` |
| Push a change to a workflow file | Waits for your Approve | Workflows: Read and write | `workflow` |
| Open a pull request, a draft by default | Waits for your Approve | Pull requests: Read and write | `repo` |
| Merge a pull request | Only as your [merge policy](/docs/ceo/house-rules#merge-policy) allows | Contents: Read and write | `repo` |
| Create a private repository | Waits for your Approve | Administration: Read and write, with All repositories | `repo` |

> [!NOTE]
> GitHub keeps check runs (the results most CI services post) away from fine-grained tokens. With a fine-grained token the Coder reads commit statuses instead, which many CI services also post. If your checks never show up, use a classic token.

## Pick a token

| | Fine-grained token | Classic token |
| --- | --- | --- |
| Best for | The narrowest access: chosen repositories, chosen permissions | Everything working first time, check runs included |
| Starts with | `github_pat_` | `ghp_` |
| Limited to | The repositories you pick, under one account or organization | Every repository your account can reach |
| Reads check runs | No, commit statuses only | Yes |
| Organizations | The organization may need to approve it first | Authorize it for single sign-on if your organization uses it |

If you are unsure, start with a fine-grained token limited to one test repository. You can widen it later.

## Create a fine-grained token

1. On GitHub, open your profile picture, then **Settings**, **Developer settings**, **Personal access tokens**, **Fine-grained tokens**.
2. Choose **Generate new token**.
3. **Token name**: something you will recognise later, such as "StellarFirm Coder".
4. **Expiration**: pick a date. When the token expires, the Coder stops as **Blocked** and asks you for a new one.
5. **Resource owner**: your own account, or the organization that owns the repositories.
6. **Repository access**: choose **Only select repositories** and pick the ones the Coder may use. Choose **All repositories** only if you want the CEO to create new repositories.
7. Under **Repository permissions**, set:
   - **Contents**: Read and write
   - **Pull requests**: Read and write
   - **Issues**: Read and write
   - **Commit statuses**: Read-only
   - **Metadata**: Read-only (GitHub sets this for you)
   - **Workflows**: Read and write, only if the Coder may change files in `.github/workflows`
   - **Administration**: Read and write, only if the CEO may create repositories
8. Choose **Generate token** and copy it. GitHub shows it once.
9. If the resource owner is an organization that reviews tokens, an owner approves it under the organization's **Settings**, **Personal access tokens**, **Pending requests**. Until then the token cannot see those repositories.

## Create a classic token

1. On GitHub, open your profile picture, then **Settings**, **Developer settings**, **Personal access tokens**, **Tokens (classic)**.
2. Choose **Generate new token**, then **Generate new token (classic)**.
3. Add a **Note**, such as "StellarFirm Coder", and pick an **Expiration**.
4. Tick **repo**. Tick **workflow** too if the Coder may change files in `.github/workflows`.
5. Choose **Generate token** and copy it. GitHub shows it once.
6. If your organization uses single sign-on, choose **Configure SSO** next to the token in the list and **Authorize** it for that organization.

## Connect it in StellarFirm

1. Open the StellarFirm desktop app and sign in.
2. Open **Integrations** and pick **GitHub**.
3. Paste the token into **Personal access token**.
4. Leave **Use live GitHub** on and press **Connect**.
5. The card shows **Connected**. Your token is saved on your computer by the desktop app, never shown back to you, and handed to one git command at a time. It is never written into the repository's settings.

## Tell the Coder where to work

The Coder needs a repository, written as `owner/repository`. Give it one of two ways.

- **In your message.** Name it, or paste its link: "Coder, in acme/web, fix the login redirect."
- **For good, per Coder.** Open **Settings**, **Coders**, edit the Coder, and under **Repository and login** choose **GitHub** as source control and fill in **Repository**. A message that names that repository then goes to that Coder. See [several Coders](/docs/personas/coder#several-coders).

Each Coder can also act as its own GitHub account. Under **Repository and login**, choose **Its own login** and paste a token for that account, for example a machine account that only has access to one repository. Its pull requests then show that account instead of yours. The token needs the same permissions as above.

## Let the CEO create a repository

You can ask for a new repository in chat. The Coder creates it after you Approve. It is always private, starts with a README so it has a main branch, and becomes that Coder's repository for the rest of the run.

What the token needs:

- A classic token with **repo**, or a fine-grained token with **Administration: Read and write** and **All repositories**. A token limited to selected repositories cannot see one that does not exist yet.
- For a repository in an organization, your account must be allowed to create repositories there, and a fine-grained token must have that organization as its resource owner.

Where it goes: the owner you name ("in the acme org"), otherwise the owner of the Coder's current repository, otherwise your own account. To keep using it after you restart the app, set it as the Coder's repository under **Settings**, **Coders**.

Creating repositories is a GitHub feature. On GitLab and Bitbucket, create the project yourself and give it to the Coder.

## Good to know

- **Pushing and merging follow your house rules.** The Coder pushes to a new branch of its own, never to your default branch, and never force pushes. Pushing waits for your Approve. Merging follows your [merge policy](/docs/ceo/house-rules#merge-policy): review only by default, and never while checks are failing or still running. Your branch protection on GitHub still applies.
- **Drafts and your GitHub plan.** GitHub allows draft pull requests on private repositories only on its Team and Enterprise plans. On a personal account or a free organization, the Coder opens a regular pull request instead and tells you so. It still waits for your review.
- **Drafts cannot be merged.** Before you ask the Coder to merge, open the pull request on GitHub and choose **Ready for review**.
- **If the clone fails**, the job stops as **Blocked** before any coding and says what to fix, usually that the token cannot read that repository.
- **Several code hosts connected?** A link or the host's name in your message picks the host. Otherwise the Coder uses the one that has a repository set.
- **GitHub Enterprise Server** is not connected from the app. Ask [support](/support) if you need it.
- **Revoke at any time.** Delete the token on GitHub and the Coder loses access straight away. Then choose **Turn off** on the GitHub card.

## Troubleshooting

| What you see | What it means | What to do |
| --- | --- | --- |
| Blocked: the Coder cannot clone the repository | The token cannot see it | Add the repository to the fine-grained token, approve the token in the organization, or authorize the classic token for single sign-on |
| Bad credentials | The token expired or was deleted | Create a new token and paste it on the GitHub card |
| Resource not accessible by personal access token | A permission is missing | Check the table above for the step that failed and add that permission |
| The push is refused on a workflow file | Workflow files need their own permission | Add Workflows: Read and write, or the `workflow` scope |
| No checks show, but GitHub shows them | Fine-grained tokens cannot read check runs | Use a classic token with `repo` |
| The merge is refused as a draft | The pull request is still a draft | Choose **Ready for review** on GitHub, then ask again |
| Creating a repository is refused | The token cannot create repositories there | Give it Administration: Read and write with All repositories, or use a classic token |

## Prompts

```prompt title="Pick up a ticket"
Coder, GitHub is connected. Pick up the top open issue on [owner]/[repository], implement it, and open a pull request for review once I Approve.
```

```prompt title="Review an open pull request"
Coder, read pull request [number] on [owner]/[repository], check its tests, and tell me what you would change before I merge it.
```

```prompt title="Triage issues"
Coder, list the open issues on [owner]/[repository], group them by area, and tell me which one to do first.
```

```prompt title="Fix a failing check"
Coder, the checks on [owner]/[repository] are failing on main. Find the cause, fix it with the smallest change, and open a pull request for review.
```

```prompt title="Create a repository"
Coder, create a new private repository called [name] in the [organization] org for [what it is for]. Then add a README that explains the plan.
```

## Next

- [Connect your code](/docs/getting-started/connect-your-code): the checklist for every code host.
- [House rules](/docs/ceo/house-rules) and [approvals](/docs/ceo/approvals): what waits for you.
- [GitLab](/docs/integrations/gitlab) and [Bitbucket](/docs/integrations/bitbucket).

---

Source: https://stellarfirm.ai/docs/integrations/github