GitLab

Connect GitLab and the Coder works on your projects the same way it does on GitHub: it reads the project, its merge requests, its issues, and its pipelines, copies the project into its own workspace, and hands you a merge request for review. When your house rules allow it, it can also merge.

At a glance#

What assistants can do#

The Coder cannot create GitLab projects. Create the project yourself, then give it to the Coder.

Pick a token#

All three kinds take the same scopes. They differ in who they act as and what they can reach.

A project token keeps access narrowest, and its merge requests show the token's own name rather than yours. On the gitlab.com Free tier, use a personal token, ideally on an account that only belongs to the projects the Coder should touch.

Create a project access token#

1. In GitLab, open the project, then Settings, Access tokens.
2. Choose Add new token.
3. Token name: something you will recognise, such as "StellarFirm Coder".
4. Expiration date: GitLab sets one within a year. When it expires, the Coder stops as Blocked and asks you for a new one.
5. Select a role: Developer. Choose Maintainer only if your merge policy lets the Coder merge into a protected branch such as main.
6. Select scopes: tick api and write_repository.
7. Choose Create project access token and copy it. GitLab shows it once.

A group access token is the same, from the group's Settings, Access tokens.

Create a personal access token#

1. In GitLab, open your avatar, then Edit profile, Access, Personal access tokens.
2. Choose Add new token. If GitLab asks which kind, choose Legacy token: it offers the scopes below.
3. Name it, such as "StellarFirm Coder", and pick an Expiration date.
4. Tick api and write_repository.
5. Choose Create token (or Generate token) and copy it. GitLab shows it once.

The token can do anything your account can do in those projects, so your own role decides whether it may push and merge.

Connect it in StellarFirm#

1. Open the StellarFirm desktop app and sign in.
2. Open Integrations and pick GitLab.
3. Paste the token into Access token.
4. Leave Use live GitLab 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.

Tell the Coder where to work#

The Coder needs a project path, written as group/project or group/subgroup/project.

• In your message. Name it, or paste its link: "Coder, in acme/platform/web, fix the login redirect."
• For good, per Coder. Open Settings, Coders, edit the Coder, and under Repository and login choose GitLab as source control and fill in Repository with the project path. See several Coders.

Each Coder can also act as its own GitLab member: choose Its own login and paste that member's token, with the same scopes and role as above.

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: review only by default, and never while the pipeline is failing or still running. Your protected branch rules on GitLab still apply.
• Drafts. A merge request the Coder opens starts with Draft: in its title. GitLab does not merge a draft, so choose Mark as ready before you ask the Coder to merge.
• Merge method. GitLab merges with your project's own merge method (merge commit, merge commit with semi-linear history, or fast-forward). Change it under the project's Settings, Merge requests.
• If the clone fails, the job stops as Blocked before any coding and says what to fix, usually that the token cannot read that project or has expired.
• Several code hosts connected? A link, the word GitLab, or "merge request" in your message picks GitLab.
• Self-managed GitLab is not connected from the app yet. The Coder's workspace must also be allowed to reach your server. Ask support if you need it.
• Revoke at any time. Revoke the token in GitLab and the Coder loses access straight away. Then choose Turn off on the GitLab card.

Troubleshooting#

Prompts#

Coder, GitLab is connected. Pick up the top open issue on [group]/[project], implement it, and open a merge request for review once I Approve.

Coder, read merge request [number] on [group]/[project], check its pipeline, and tell me what to fix before it merges.

Coder, the pipeline on [group]/[project] is failing. Read the latest results, tell me why, and propose the smallest fix.

Next#

• Connect your code: the checklist for every code host.
• House rules and approvals: what waits for you.
• GitHub and Bitbucket.