Connect GitLab to Windshift

What the integration gives you

The connection lives in your Windshift instance and calls the provider API directly.

• Link repositories: Discover the repositories the connection can reach, then link the ones a workspace tracks.
• Connect changes to work items: Link pull requests or merge requests to the work item, and read item keys from branch names and commit messages.
• Start from a work item: Create a branch and open a change request without leaving the item.
• Follow review threads: Read review comments so a teammate or an agent can continue from the discussion.
• Track releases: Attach a tag to a milestone and see which changes shipped with it.
• Stay current: Webhooks update linked repositories after each push or review event, with polling as a fallback.
• Issue sync is available on the GitHub integration only. This integration links branches, commits, and change requests, not its issue tracker.

Ways to connect

Windshift connects to GitLab.com or a self-managed GitLab instance (CE or EE) with an OAuth application or an access token. Repository discovery, branches, commits, merge requests, review threads, releases, and webhooks run through the GitLab REST API v4.

Windshift creates branches and change requests, so the connection needs write access, not only read access.

• OAuth App: Each user authorizes their own GitLab account. Windshift refreshes the token automatically, so users stay connected until they revoke access.
• Access token: GitLab accepts personal, project, and group access tokens. Prefer a project or group token for a bot or server-to-server integration.

Set up the integration

A Windshift administrator configures the provider once. Workspace administrators then link repositories.

Keep the credentials with the team that owns the Git host. Rotate the token or secret on the same schedule as your other service accounts.

• Create the credentials in GitLab: Register an OAuth application with the api scope, or create a personal, project, or group access token. Set the redirect URI to the callback URL that Windshift shows.
• Add the provider in Windshift: Open Settings, SCM Providers, add a provider, choose GitLab and the authentication method, then paste the credentials. Leave the base URL empty for GitLab.com, or enter your instance URL.
• Connect a workspace and link projects: Repository discovery lists the projects that the connecting account can access. Link the projects the workspace tracks.
• Create the project webhook: Generate the webhook secret in Windshift, then add the callback URL and secret to the project in GitLab. Enable push, tag push, merge request, note, and release events.

Permissions and scopes

Exact permission names follow the provider. Check them against your instance policy before you grant access.

• Link and browse projects: The connecting account is a member of the project.
• Create branches, merge requests, and comments: Developer role (access level 30) or higher.
• Create the project webhook: Maintainer role or higher.
• OAuth scope: api

Self-hosted notes

Set the base URL to your instance root, for example https://gitlab.example.com. Both servers must reach each other for OAuth callbacks, webhooks, and API calls. If the instance uses a self-signed certificate, the Windshift host must trust the certificate authority.

Frequently asked questions

Does Windshift support self-managed GitLab?

Yes. Windshift works with GitLab.com and self-managed GitLab CE and EE. Set the base URL to your instance.

Can I connect more than one GitLab instance?

Yes. Add a provider for each instance, with its own base URL, then link the projects each workspace tracks.

Can I restrict a provider to specific workspaces?

Yes. A system administrator can restrict a provider to an allowlist of workspaces.