Connect your code

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.

Checklist#

• You have the StellarFirm desktop app and are signed 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.
• You ran a read-only test prompt and got a sensible answer.

Choose your token#

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.

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.

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.

Decide what happens after the work#

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

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.

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:

Coder, in [repository], fix [one small thing]. Run the tests and open a pull request for review once I Approve.

When something is off#

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: the full walk-through to a pull request.
• Delegate work: where you can hand work to your assistants.
• The Coder: everything it can do.