Help

How to use Speclr

Connect GitLab

For organisation admins. Connects your Speclr organisation to GitLab once, so project teams can hand stories over to GitLab projects and GitLab Issues.

Updated

Use a dedicated machine account

  • Clear authorshipEvery merge request, issue and comment Speclr creates appears under the account you connect.
  • Survives people leavingA personal account takes all hand-overs down with it when its owner leaves.
  • Own request budgetGitLab limits requests per user. A machine account keeps Speclr's status reads for all projects apart from anyone's own work.

Speclr works with GitLab on gitlab.com. Self-managed GitLab instances cannot be connected.

  1. Create the account and add it to your groups

    Sign up a GitLab account such as speclr-bot-acme with a team mailbox. Add it as a member of the groups or projects your teams use. Speclr acts as this account, with the roles it has there.

    • Two-factor authentication on, recovery codes stored with the team
    • Role "Developer" or higher in each project, not group owner
    • "Maintainer", or an allowance to push, where Speclr commits directly to a protected branch
  2. Connect in Speclr, signed in as the machine account

    Open Organisation settings › Integrations › Discover and choose "Connect" on GitLab. Only organisation admins see the integrations. When GitLab asks you to sign in, use the machine account, not your own. A private browser window avoids mix-ups.

    GitLab then shows "Speclr is requesting access to your account on GitLab" and "Speclr added this OAuth application". GitLab shows no app logo on that page, for any app.

    Back in Speclr, the connection appears under Yours and names the account it acts as. Check that it is the machine account.

  3. Check the permissions

    Speclr requests only the GitLab OAuth scope api. It works with the account's own roles, so Speclr can do no more than the account itself. With Developer, the account can:

    Projects
    list, create, read and write files on branches that are not protected
    Merge requests
    open and read
    Issues
    create, edit and order
    Labels and milestones
    reuse or create
    Groups
    read, to offer them as allowed owners
  4. Pick the GitLab project in each Speclr project

    Any member of a Speclr project can do this. Open Project settings › "Integrations". Under "Repository", the list shows the GitLab projects in which the machine account is Developer or higher. If GitHub is connected too, both are listed, each in its own group. Once saved, the row reads "Saved · write access confirmed".

    "Create new project…" creates a private project with a README, in a group or in the account's own namespace. If GitHub is connected too, the entry reads "Create new repository…". In a group, the account needs the role the group allows to create projects.

    To use GitLab Issues as the ticket system, choose the GitLab project under "Work items". It then shows as "GitLab Issues". There is no "Board" row for GitLab: see the order below.

What Speclr creates in GitLab

In the repository, Speclr opens a merge request from a branch speclr/…. It carries AGENTS.md, the docs/ foundation set (with docs/risks.md once your team tracks risks) and a spec and feature file per story. With "Commit directly instead of opening a change request", Speclr commits to the target branch instead. It never force-pushes and never overwrites a change it has not seen.

For each story you hand over to GitLab Issues:

  • An issue. Speclr keeps its own part of the description; text your team adds outside it is never touched.
  • Labels for the story's activity and step. GitLab compares labels by case. A label of the same name in the project or a parent group is reused.
  • The milestone, found by its exact title in the project or a parent group, open or closed, or created in the project.
  • The priority order. GitLab has no order per board: every board of the project and the issue list's "Manual" sort share one order. Speclr places the issues in that order, so there is no board to choose.

Status and merge requests

Speclr reads the state of each issue and the project's merge requests, and changes neither. A merge request counts for a story when its description names the issue with a closing pattern, for example Closes #12, or with Fixes, Resolves or Implements. The story then shows the merge request with its number, such as !34.

A branch counts when it starts with the issue number, the way GitLab's "Create branch" names it (12-set-a-spending-limit), or contains the story id, such as US-014. A closed issue counts as done; one closed as a duplicate counts as discarded. GitLab has no "closed as not planned".

Optional: allowed owners

Limit project teams to GitLab projects of chosen namespaces, e.g. acme. An allowed group includes its subgroups, so acme also allows acme/platform. Projects outside the list receive nothing.

Reconnect or disconnect

Reconnect when the connection shows "Needs reconnect", as the same machine account. Another account first names the affected projects.

Disconnecting names them too. Targets and links stay; status turns unknown.

Troubleshooting

  • Wrong account connected: reconnect as the machine account.
  • A project is missing from the list: the account needs Developer or higher in it. Also check the allowed owners.
  • "Speclr has no write access to acme/shop. …": give the account Developer or higher in the project.
  • "The target branch does not accept direct commits.": the branch is protected. Make the account Maintainer, allow it to push under the project's Settings › Repository › Protected branches, or turn direct commits off.
  • A merge request or branch does not show at the story: name the issue in the description, such as Closes #12, or start the branch name with the issue number.
  • Authorisation cancelled or failed: nothing was connected. Start again from Discover.