Add first-class GitLab SCM provider support

[oshuej198]

Problem

Windshift currently supports GitHub and Gitea/Forgejo as SCM providers, but not GitLab. Teams using GitLab cannot connect their repositories to a workspace or use the existing development-panel and SCM automation features.

Although GitLab is mentioned in some UI copy and schema comments, provider_type: gitlab is rejected by the backend. Configuring GitLab as a Gitea provider is not a viable workaround because the API routes, authentication, project identifiers, and merge request payloads differ.

Proposed solution

Add a first-class GitLab SCM provider with support for both GitLab.com and self-managed GitLab instances.

Provider and authentication

• Add gitlab as a supported SCM provider type.
• Support Personal Access Token and OAuth authentication.
• Allow an optional base URL for self-managed GitLab; default to GitLab.com.
• Discover and select accessible projects/repositories.
• Correctly support nested group paths such as group/subgroup/project.

Repository and merge request integration

• List and fetch projects, branches, commits, tags, releases, and merge requests.
• Create branches and merge requests from a Windshift item.
• Map GitLab merge request states to Windshift's open, merged, and closed states.
• Use the GitLab project-scoped merge request IID as the external PR/MR number.
• Detect Windshift item keys in merge request titles/descriptions, source branch names, and commit messages.
• Display GitLab merge requests, branches, and commits in the item's Development section with correct GitLab URLs.
• Support merge request comments/reviews and repository permission checks where the equivalent GitHub/Gitea features are available, including the @agent continuation flow.
• Register/delete GitLab webhooks, or document polling as the supported synchronization mechanism.

Tags, releases, and milestones

GitLab should have parity with the existing SCM tag/release workflows:

• Implement the provider capabilities required for listing tags, comparing commits between refs, and listing/creating releases.
• Allow a GitLab tag or release to be attached to a Windshift milestone/release record.
• Preserve the existing scm_tag_created and release-branch automation behavior for GitLab repositories.
• Show the linked tag/release and a direct link back to GitLab in the milestone UI.
• Allow items referenced by commits between release tags to be associated with the corresponding milestone.

Expected workflow

1. An administrator configures a GitLab.com or self-managed GitLab provider.
2. A workspace connects the provider and selects one or more GitLab projects.
3. A developer creates a branch or merge request containing an item key such as PROJ-123.
4. Windshift automatically links the branch, commits, and merge request to PROJ-123 and keeps the MR state synchronized.
5. When a matching release tag is created, existing tag/release automation can create or promote a milestone, attach the GitLab release, and associate shipped items.

Acceptance criteria

• GitLab appears as a selectable SCM provider.
• PAT and OAuth work with GitLab.com and self-managed GitLab.
• Projects in nested groups can be discovered and synchronized.
• Branch, commit, and merge request links are detected from Windshift item keys.
• Users can create a GitLab branch and merge request from an item.
• Merge request status and metadata are displayed and refreshed correctly.
• GitLab tags/releases participate in the existing milestone and release automation.
• GitLab-specific URLs use /-/merge_requests/, /-/tree/, and /-/commit/ where appropriate.
• Provider behavior is covered by unit/integration tests and documented.
• Treat GitLab tags and releases as related but distinct entities: a tag may exist without a release, while an associated release should synchronize its name, description, release date, status, assets, and external URL.
• Creating a release from Windshift should use an existing Git tag or create it from the selected branch/commit when necessary.
• Release synchronization must be idempotent per project and tag name.

Notes

This likely requires a dedicated GitLab provider rather than adapting the Gitea driver. GitLab uses /api/v4/projects/:id/..., URL-encoded project paths, and merge requests instead of the GitHub/Gitea pull request API shape.

[stefan-ernst]

Yes Gitlab was originally planned but then scoped out to deliver a working Gitea integration first. I think we can start working on this, I would however wait to release 0.8.8 before merging something as big as this to main

One important question: In using both Gitea / ForgeJo and Github, I found Github Apps to be superior to OAuth for this type of integration. Does Gitlab support such an integration pattern?

[oshuej198]

Thanks — and I agree that waiting until 0.8.8 is released before merging this would be sensible.

I looked into the authentication model. The short answer is that GitLab does not currently provide a 1:1 equivalent to GitHub Apps.

GitLab supports user-owned, group-owned, and instance-wide OAuth applications. OAuth access tokens are short-lived and refreshable, but requests are still made on behalf of the user who authorized the application. A group-owned application centralizes ownership of the OAuth registration, but it does not create a separate installation identity, allow repository selection during installation, or let the application mint installation tokens from a private key.
The closest bot-style alternative is a Project or Group Access Token. GitLab creates a dedicated, non-billable bot user for such a token and limits it to one project or a group hierarchy. Its permissions can be controlled through a role and token scopes, and the token can be expired, rotated, or revoked. The trade-off is that this is an administrator-provisioned credential rather than an application installation flow.
For the current implementation I therefore used:

• OAuth authorization-code flow with access-token refresh for convenient per-user connections.
• Token authentication for server-to-server use. GitLab accepts personal, project, and group access tokens through the same PRIVATE-TOKEN authentication mechanism, so the implementation can already use all three.
• Project webhooks for event-driven synchronization.
  I think we should present the token option as “Access Token” rather than specifically “Personal Access Token”, and recommend Project or Group Access Tokens for bot-style installations. That gives us the closest GitLab equivalent while keeping OAuth available for simpler setups.
  GitLab also has an open request for first-class OAuth application bot identities, which illustrates the remaining gap compared with GitHub Apps: https://gitlab.com/gitlab-org/gitlab/-/work_items/300388