GitLab Integration
Connect your GitLab account to Devpilot via OAuth to deploy projects and enable automatic deployments via webhooks.
GitLab Integration
The GitLab integration links your GitLab account to a Devpilot workspace using OAuth. Once connected, Devpilot can list your projects and branches, pull source code for deployments, and register webhooks for automatic deployment on push. This integration works with GitLab.com and self-managed GitLab instances configured by your Devpilot administrator.
Prerequisites
- A GitLab account with access to the projects you want to deploy
- Maintainer or Owner role on projects where Devpilot should register webhooks
- An active Devpilot workspace
Connecting GitLab
Open Integration Settings
Navigate to Workspace Settings > Integrations and select Connect on the GitLab card under Source Control.
Authorize Devpilot on GitLab
GitLab's OAuth consent screen lists the scopes Devpilot requests. Review them and select Authorize.
Confirm the Connection
GitLab redirects you back to Devpilot. The Integrations page shows GitLab as connected along with the GitLab username linked to the integration.
GitLab issues short-lived access tokens together with a refresh token. Devpilot refreshes your access token automatically — you do not need to reconnect unless you revoke access from GitLab's Settings > Applications page.
Permissions Granted
Devpilot requests the following GitLab OAuth scopes:
| Scope | Why Devpilot needs it |
|---|---|
api | Read and write access to the GitLab API for project metadata and webhook management. |
read_api | Read-only fallback access to project and branch data. |
read_repository | Read repository contents during deployments. |
write_repository | Register deployment-related references when required. |
Using GitLab for Deployments
Selecting a Project and Branch
On the deployment form, the project selector lists every GitLab project accessible through your integration. Search by name to narrow the list. Branches are fetched live from GitLab after you pick a project, so new branches appear without refreshing.
Build and Deploy
Devpilot clones the selected branch on every deployment run to guarantee the latest code is used.
Webhook Support
How Webhooks Work
When auto-deploy is enabled, Devpilot registers a GitLab push webhook on the project. Every push to the watched branch triggers a new deployment.
Enabling Webhooks
Toggle Auto-deploy on push in the deployment form and pick the branch to watch. Devpilot handles the webhook registration for you.
You need the Maintainer or Owner role on the project for webhook registration to succeed. Developers and lower roles cannot create project webhooks in GitLab.
Troubleshooting
Projects Not Appearing
- The integration only surfaces projects the GitLab user is a member of. Request access to any missing project from its owner.
- For self-managed GitLab instances, confirm the OAuth application has been configured correctly by your administrator.
Token Errors
- If Devpilot reports that the GitLab token is expired or invalid, open the GitLab integration and select Refresh Token. If that fails, remove and reconnect the integration.
Webhook Delivery Failures
- Open GitLab > Project > Settings > Webhooks and inspect the most recent delivery for the HTTP response from Devpilot.
- Make sure the pushed branch matches the branch configured on the deployment.
Disconnecting GitLab
Go to Workspace Settings > Integrations, open the GitLab integration, and select Remove. The access and refresh tokens are deleted from the workspace. Existing GitLab webhooks remain on your projects and should be removed manually from each project's webhook settings.