GitLab

TruStacks connects to GitLab the same way it connects to GitHub and Azure DevOps: it reads your service repos and opens merge requests in your platform repo. A human merges. On GitLab it connects with an access token that you create, on gitlab.com or on your own GitLab instance.

What you need

• The GitLab URL: https://gitlab.com, or your self-managed instance’s URL, for example https://gitlab.example.com, or https://example.com/gitlab if GitLab runs under a path. It must be HTTPS, with no username or password in it, no query and no fragment, and without /api/v4 on the end, so the token is never sent to a host you didn’t mean.
• The project’s full path, including every group it sits in, for example acme/platform or acme/delivery/platform. Nested groups work.
• An access token, created as below.
• A connected runner (Runner install). The token is delivered to it, not stored by TruStacks.

Create the token

Prefer a project or group access token. It belongs to a bot user that is a member of only that project or group. GitLab treats these tokens as internal users, so on a self-managed instance a token can also reach every project with Internal visibility; keep the platform repo Private if that matters to you. On gitlab.com these need the Premium or Ultimate tier; on a self-managed instance every tier has them. Create one in the project (or group) under Settings → Access tokens.

A personal access token works too, but it acts as the person who created it, with everything that person can reach, and merge requests show that person as the author.

GitLab has no narrower scope than api that can open a merge request, which is why the platform repo’s token needs it.

Never give it the Maintainer or Owner role. TruStacks doesn’t merge, and your protected branches should stay out of its reach. The role alone doesn’t guarantee that: a protected branch can allow Developers to push or merge. Set the platform repo’s default branch to Allowed to push and merge: No one and Allowed to merge: Maintainers (or named people), so the token can’t push to it or merge into it.

Connect the repo

In Applications, open the Application and choose Connect a repo, pick Service or Platform, then GitLab. Enter the GitLab URL, the project path, a name for the repo in TruStacks, the token type (project or group access token, or personal access token), and the token.

What happens to the token

1. The control plane hands it to your runner sealed, so only your runner can open it.
2. Your runner checks it with one read-only call to the project.
3. If the check passes, the runner writes it to a Secret in its own namespace and confirms.

TruStacks keeps only whether the token works: configured or invalid. The token itself is never stored in the TruStacks database and never logged.

Delivery states

Replace the token

Open the service and choose Replace token, then paste the new token. It’s delivered and checked the same way, and your current token keeps working until the new one passes the check. If GitLab refuses the new token, you’ll see that, and the previous one stays in use. If your runner doesn’t pick it up in time, the status shows it expired: paste it again. Do this before the old token expires.

Merges and approvals

TruStacks never merges. Protect the platform repo’s default branch and require approvals.

Because the token lives in your cluster, your runner checks the platform repo and reports what it sees:

• for each merge request TruStacks opened: whether it merged, when, who merged it, and who approved it;
• every merge request merged into the platform repo’s default branch, not only TruStacks’ own, with the same details.

GitLab reports approvals on every tier, including Free; approval rules (how many approvals are required) are a paid feature, and TruStacks doesn’t need them to record who approved. That is the record behind “approved by a named person”. If the approvals can’t be read, the merge is still recorded, as approver not recorded, never as nobody approved.

Your Stack file

The Stack page shows environment-profile.yaml from your GitLab platform repo. Your runner reads it (the token never leaves your cluster) and reports it. Until the first report arrives, the Stack page says it’s waiting for the runner.

Pipelines

Connecting GitLab doesn’t choose your CI; your Stack file does. When its primary CI platform is GitLab CI:

ci_cd_platform:
  - provider: gitlab_ci
    primary: true

proposals write a GitLab CI pipeline to the platform repo at .gitlab/ci/ci-<service>.yml, and your service repo’s .gitlab-ci.yml includes it at a commit SHA. TruStacks never writes the platform repo’s root .gitlab-ci.yml or anything in the service repo. See GitLab CI for the jobs, the include, the policy check and the runner and permissions it needs.

When the primary provider is azure_pipelines, proposals write Azure Pipelines files, and otherwise GitHub Actions workflows. Neither runs in GitLab CI.

What TruStacks does not do on GitLab

• Store your token. Only its status.
• Merge, or change protected branches or approval rules.
• Write to your service repos, including their .gitlab-ci.yml. You add the include yourself.

Troubleshooting

Where to go next

• Connect a repo: service and platform repo roles
• GitLab CI: the pipeline TruStacks writes
• Azure DevOps: the same flow for Azure Repos