Connect GitLab

1. 1

   Open Integrations

   In your workspace dashboard, open the Integrations tab. It lists your workspace connections: the identities Sarcio uses to open merge requests, post the sarcio/approval status, read pipelines and dispatch remote builds. They belong to the workspace, not to a person. Under Code hosts, the token form comes first and the personal quick start below it. QA members don't see this tab.

2. 2

   Create a project access token (recommended)

   A project access token creates a bot member of the project. It belongs to the project, not to a person, so it keeps working when people leave and reaches nothing else.

   • In the project, go to Settings → Access tokens → Add new token.
   • Token name: Sarcio. The bot's name is what merge requests and commits show, so name it Sarcio so they read clearly.
   • Expiration date: required. GitLab.com caps how far out it can be (a year on the account we tested), so plan to rotate. Sarcio reads the date and reminds workspace admins before it lapses.
   • Role: Developer.
   • Scopes: api and write_repository. Merge requests, commit statuses and pipelines need api; write_repository covers cloning and pushing the fix branch.

   Project access tokens and your GitLab tier

   On GitLab.com, project and group access tokens need a paid tier (Premium or Ultimate). Self-managed GitLab offers them on every tier. On GitLab.com Free, create a dedicated GitLab user for Sarcio, give it Developer on the project, and use its personal access token with the same scopes.

   Several projects in one group can share a group access token with the same settings.

3. 3

   Save the token in Sarcio

   On the Integrations tab, under Add a bot or project access token (recommended), enter gitlab.com (or your self-managed host), leave the provider on Auto-detect, paste the token and press Save token.

   When you save, Sarcio asks GitLab who the token belongs to (GET /user, an identity read that needs no extra scope). Project and group access token bots, and service accounts, show Bot token. A person's token, including a dedicated bot user's, shows Personal with a banner. If GitLab can't be reached, the token still saves, badged Owner unknown.

   What Sarcio checks, and what the warnings mean

   Sarcio also checks the token can do what it needs on the projects your sites point at on that host. It reads the token's scopes and expiry from GET /personal_access_tokens/self (which answers for personal, project and group access tokens alike) and the token's role on each project from GET /projects/:id. Anything missing shows as a warning on the connection under Workspace connections; warnings never stop the save.

   • Missing api scope. Sarcio can't create the fix branch, commit or open the merge request. Create a new token with api (scopes can't be changed after creation).
   • Role Reporter can't push branches. The token's role on that project is below Developer. Developer can push Sarcio's new, unprotected fix branch; Maintainer is only needed if a protected branch rule (such as a wildcard) covers it. A healthy check notes which role it found.
   • Can't reach group/project. The token was created on another project, or the site's repo owner and name aren't the GitLab paths.
   • This token is revoked or expired, or GitLab rejected this token: create and save a new one.

   After fixing something on GitLab's side, press Re-check on the connection: it runs the owner probe and these checks again on the stored token, so you never paste it twice. The expiry GitLab reports shows as a chip on the connection, and workspace admins get an email 14 and 3 days before it lapses (once per threshold). Saving a new token resets the reminders.

4. 4

   Quick start: connect a personal account

   Trying Sarcio out? Under Quick start: connect a personal account, press Connect GitLab and authorize the application on gitlab.com. Sarcio requests api, read_repository and write_repository, and refreshes the access on its own. GitLab skips the consent screen if the account has authorized the application before.

   It is quick, but it connects the workspace as you:

   • Merge requests, commits and statuses appear as you.
   • It reaches every project your account can, not just one.
   • The connection stops working if you leave or lose access.
   • The connection wears the Personal badge, with a warning banner on the Integrations tab.

   OAuth connects gitlab.com; a self-managed GitLab uses a token.

   Connecting over OAuth replaces a token saved for the same host, and saving a token replaces an OAuth connection. Revoke the credential you no longer use on GitLab's side too.

5. 5

   Point the site at its project

   For GitLab, the repo owner is the group path (not its display name) and the repo name is the project path.

   On the Sites tab, press Manage next to the site and open Repository & source. Fill in the repository and the file a fix edits. What each field means.

   Repository & source

   Forge host          gitlab.comRepo owner          acme-groupRepo name           helpdeskDefault branch      mainSource file         src/main/resources/templates/signup.htmlServer source file  src/main/java/com/acme/SignupApi.java

6. 6

   Approve a patch and get a merge request

   When a reviewer approves a patch and it goes live, Sarcio opens a merge request into the default branch. The title and branch carry the Jira key when ticketing is on, and the description has a Sarcio context section with the report, the live patch operations, the expiry, who approved it and a link to the report in Sarcio. Each commit gets one Approved-in-Sarcio-by: Ada L. trailer per approver. Approvers are named, never by email, and never added as Co-authored-by. An approver who linked their GitLab account (below) reads as @their-username in the description and the approval status. If an admin turns on acting links, an approver can also let Sarcio approve the merge request as them, using the api scope GitLab requires for approvals, on patches they approve with Also act as me ticked (see acting links).

   

   Enlarge

   

   Enlarge

   Get @mentioned: link your GitLab account

   Any member can open Account and press Link GitLab. GitLab asks for one scope, read_user, and Sarcio stores no token. Merge requests you approved then name you as @your-username. What a link can and cannot do.

   

   Enlarge

   Sarcio's approval on the merge request

   Sarcio posts a sarcio/approval commit status on the merge request's head commit: success with the approvers' names and the risk rating (for example Approved in Sarcio by Ada L. and Bo K. · elevated risk), linking to the report, and failed if the live patch is retired or expires before the merge request merges. It shows in the merge request's pipeline widget. Treat it as a visible signal rather than a merge gate: Pipelines must succeed is about pipelines, and GitLab does not promise an external status is counted alongside your CI pipeline.

   While the merge request is open, Sarcio also reads your pipeline's job results for its head commit and shows them as a Build: passing / failing / running chip next to the pull request on the report page and in Live patches.

   "Before you can run pipelines, we need to verify your account"

   GitLab.com requires account identity verification before its shared runners run any pipeline, merge request and branch pipelines alike. It is a one-time check on the GitLab user, separate from sign-up email verification, and it doesn't affect the merge request itself. Press Verify my account on the pipeline page, enter a phone number, solve the puzzle and type the SMS code. Then open the merge request's Pipelines tab and press Run pipeline. You don't need your own runner.

   

   Enlarge

7. 7

   If the merge request fails, retry it

   The patch stays live even when the merge request can't be opened. The report page shows a warning with Retry pull request. Fix the cause, then press it.

   

   Enlarge

Troubleshooting

• 401 Unauthorized. The token expired, was revoked, or lacks the api scope, or the OAuth authorization was revoked on GitLab. Save a new token or connect again, then Retry pull request.
• 403 Forbidden. The token's role is below Developer, or branch protection blocks the push. Raise the role or allow Developers to push new branches.
• Project not found. Check the site's repo owner and name are GitLab paths, including the full group path.
• No Access tokens page in the project settings. On GitLab.com Free, project access tokens aren't available. Use a dedicated bot user's personal access token instead.
• The connection shows Personal or Owner unknown. Personal means the token belongs to a user account. Owner unknown means Sarcio couldn't ask GitLab when you saved; press Re-check on the connection.
• The connection shows warnings. See what the warnings mean, fix them on GitLab, then press Re-check.
• Creating a second group asks you to verify. An unverified GitLab.com account can own only one group. Verify the account first.
• After connecting you land on another dashboard address. Older deployments return from the provider to a shared dashboard address instead of your workspace. The connection is saved either way: go back to your workspace address (e.g. acme.sarcio.io) and it's listed on the Integrations tab.

Token scopes and OAuth scopes in detail: Repository access. To show merge requests on Jira tickets, see GitLab for Jira Cloud.