# Connect your code

> The checklist for giving the Coder a repository on GitHub, GitLab, or Bitbucket: which token, which permissions, where to connect it, and a first test.

Before the Coder can work on your code, it needs three things from you: a token from your code host, that token connected in StellarFirm, and a repository to work in. This page is the checklist for all three, on GitHub, GitLab, or Bitbucket. Each host's own page has the exact clicks.

> [!IMPORTANT]
> Today you connect a code host 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.

## Checklist

- [ ] You have the StellarFirm desktop app and are [signed in](/docs/getting-started/sign-in).
- [ ] You know which repository the Coder should work in. A small or test repository is a good first choice.
- [ ] You created a token on your code host with the permissions below, and nothing more.
- [ ] You connected the token under **Integrations** and the card shows **Connected**.
- [ ] You told the Coder its repository, in your message or under **Settings**, **Coders**.
- [ ] You chose what happens after the work in your [house rules](/docs/ceo/house-rules).
- [ ] You ran a read-only test prompt and got a sensible answer.

## Choose your token

| Code host | Narrowest token | Token that does the most | What you paste | Full guide |
| --- | --- | --- | --- | --- |
| GitHub | Fine-grained token, chosen repositories only | Classic token with `repo` | The token | [GitHub](/docs/integrations/github) |
| GitLab | Project access token (Premium or Ultimate on gitlab.com) | Personal access token | The token | [GitLab](/docs/integrations/gitlab) |
| Bitbucket | Repository access token | Atlassian token with scopes | The token, plus the account email for an Atlassian token | [Bitbucket](/docs/integrations/bitbucket) |

Start narrow. You can always make a new token with more access later, and a narrow token limits what any mistake can touch.

## The permissions, side by side

Give the token what the steps you want need. Reads run on their own; every write waits for your Approve or follows your merge policy.

| Step | GitHub fine-grained token | GitLab token | Bitbucket repository access token | Bitbucket Atlassian token |
| --- | --- | --- | --- | --- |
| Read the code, pull or merge requests, changed files | Contents, Pull requests, Metadata: Read | `api` | Repositories, Pull requests: Read | `read:repository`, `read:pullrequest` |
| Read check, pipeline, or build results | Commit statuses: Read | `api` | Repositories: Read | `read:repository` |
| Read and open issues | Issues: Read and write | `api` | Not possible | `read:issue`, `write:issue` |
| Push its branch | Contents: Read and write | `write_repository`, Developer role | Repositories: Write | `write:repository` |
| Open a pull or merge request | Pull requests: Read and write | `api`, Developer role | Pull requests: Write | `write:pullrequest` |
| Merge, when your rules allow | Contents: Read and write | `api`, Maintainer for a protected branch | Pull requests: Write | `write:pullrequest` |
| Create a repository | Administration: Read and write, All repositories | Not available | Not available | Not available |

Bitbucket's Atlassian scopes all end in `:bitbucket`, for example `read:repository:bitbucket`. A GitHub classic token with `repo` covers its whole column, and also reads check runs, which fine-grained tokens cannot.

## Connect it

1. Open the StellarFirm desktop app and sign in.
2. Open **Integrations** and pick your code host from the **Code hosting** shelf.
3. Paste the token. For a Bitbucket Atlassian token, also enter the account email.
4. Leave the live switch on and press **Connect**.
5. Check that the card shows **Connected**.

The desktop app saves the token on your computer. It is never shown back to you, never goes into chat, and is handed to one git command at a time when the Coder pushes. See [security](/docs/trust/security).

## Give the Coder its repository

The Coder works in one repository at a time. Tell it which one:

- **In each message.** Write it as `owner/repository` (GitLab: `group/project`; Bitbucket: `workspace/repository`), or paste its link.
- **Once, per Coder.** Under **Settings**, **Coders**, each Coder has **Repository and login**: the code host, the repository, and whose login it uses. A message that names that repository goes to that Coder.

**Shared or own login.** By default every Coder uses the token you connected under Integrations, so its work shows your name on the code host. Choose **Its own login** to give a Coder a separate token, for example a machine account that only has access to one repository. Running several Coders? Give each its own repository and, if you like, its own login. See [several Coders](/docs/personas/coder#several-coders).

## Decide what happens after the work

The token says what the Coder *could* do. Your house rules say what it *does*.

| Setting | Where | Start with |
| --- | --- | --- |
| Merge policy | [House rules](/docs/ceo/house-rules#merge-policy) | Review only: the Coder opens a pull request and stops |
| Shipping | House rules | Never |
| Auto-approve | [Approvals](/docs/ceo/approvals) and Settings | Everything off |
| Written rules | Your company brief | Three lines on branches, tests, and what never to touch |

The Coder opens drafts. A draft cannot be merged on any of the three hosts, so mark it ready for review on the host before you ask the Coder to merge it.

## Test the connection

Run a read-only prompt first. Nothing is written, so nothing waits for Approve.

```prompt title="Read-only check"
Coder, in [repository], list the open pull requests and tell me what each one is waiting for.
```

If the answer lists your real pull requests, the token works. Then try a small change:

```prompt title="First small change"
Coder, in [repository], fix [one small thing]. Run the tests and open a pull request for review once I Approve.
```

## When something is off

| What you see | Usual cause | Fix |
| --- | --- | --- |
| The job stops as **Blocked** before coding | The token cannot read the repository, or has expired | Check the repository name and the token's access and expiry |
| The Coder says no code host is connected | Nothing is connected, or the card is turned off | Connect the token under Integrations in the desktop app |
| Reads work, but the push or pull request is refused | The token is read only, or the role is too low | Add the write permission from the table above |
| No check results | GitHub fine-grained tokens cannot read check runs | Use a classic token, or a CI that posts commit statuses |
| The merge is refused | The pull request is a draft, checks are not green, or branch protection blocks it | Mark it ready, wait for green, or adjust the protection |

## Keep it safe

- **Least access.** Only the repositories and permissions the Coder needs.
- **Set an expiry.** A token that expires limits the damage of a leak. The Coder tells you when it needs a new one.
- **Never paste a token in chat.** Tokens go only into Integrations or **Settings**, **Coders**.
- **Revoke on the host.** Deleting the token on GitHub, GitLab, or Bitbucket stops access straight away. Then choose **Turn off** on the card.

## Next

- [Your first goal](/docs/getting-started/first-goal): the full walk-through to a pull request.
- [Delegate work](/docs/ceo/delegate-work): where you can hand work to your assistants.
- [The Coder](/docs/personas/coder): everything it can do.

---

Source: https://stellarfirm.ai/docs/getting-started/connect-your-code