GitLab integration

Use this guide when App Services should build from GitLab repositories. dFlow connects through OAuth so you can pick repositories and branches from the dashboard, register push webhooks, and show deploy status on commits.

For public repositories or one-off clones without a connected account, you can still use a repository URL with an optional Personal Access Token (PAT). See Manual deployment below and Git source integrations under Integrations in the sidebar for PAT scope details shared with other token-based Git hosts.

For the shortest dFlow Cloud path, see Integrations overview under Integrations in the sidebar.

Before you startCopy Anchor Link

• You can sign in to gitlab.com or your self-hosted instance as a user who may authorize OAuth applications.
• You know which repositories and branches map to which Application and Environment (see How dFlow is structured under Core Concepts in the sidebar).
• Review Integration permissions and prerequisites for least-privilege and token hygiene.

1. Open GitLab in IntegrationsCopy Anchor Link

1. Sign in to the dFlow dashboard (for example app.dflow.sh on dFlow Cloud).
2. Open Integrations (or Settings → Integrations, depending on your UI version).
3. Select GitLab and click Connect GitLab.

2. Connect gitlab.com (recommended)Copy Anchor Link

1. In the connect dialog, choose GitLab.com.
2. Sign in on gitlab.com when redirected and approve the requested scopes: api, read_user, read_repository.
3. Return to dFlow when authorization completes.

Expected outcome: GitLab shows as connected and repository pickers list repos your account can access.

dFlow uses a shared OAuth application on gitlab.com. You do not create your own OAuth app for gitlab.com.

3. Connect self-hosted GitLabCopy Anchor Link

Use this when your organization runs GitLab on its own domain (for example https://git.example.com) instead of gitlab.com.

dFlow cannot use the shared gitlab.com OAuth app on a private instance. Register an OAuth application on that GitLab instance, then paste the credentials into dFlow when connecting.

Where to create the applicationCopy Anchor Link

Depending on your GitLab policy, create the OAuth application in one of these places:

OAuth application fieldsCopy Anchor Link

Use these values when creating the application. The connect dialog in dFlow shows the exact Redirect URI for your deployment (copy it from there).

Redirect URI examples

• dFlow Cloud staging or production: use your public dashboard URL (same host as NEXT_PUBLIC_WEBHOOK_URL when set).
• Local development: your ngrok or tunnel URL, for example https://abc123.ngrok-free.app/api/webhook/providers/gitlab.

Why each scope matters

If api or read_repository is missing, OAuth may appear to succeed but repo pickers, webhooks, or deploys will fail with permission errors.

After you save the application, GitLab shows:

• Application ID → paste into dFlow as OAuth application ID
• Secret → paste into dFlow as OAuth application secret (shown once; copy it immediately)

Connect from dFlowCopy Anchor Link

1. In the connect dialog, select Self-hosted GitLab.
2. Follow the in-dialog setup guide (redirect URI, scopes, and field names).
3. Enter your instance URL (for example https://git.example.com).
4. Click Test connection to verify dFlow can reach GET /api/v4/version.
5. Paste the Application ID and Secret.
6. Click Connect GitLab and complete authorization on your instance.

Self-hosted connections store your OAuth credentials encrypted so token refresh continues to work after the initial connect.

HTTPS and network access: Production dFlow requires HTTPS instance URLs. Your GitLab instance must be reachable from the dFlow dashboard for OAuth and API calls. GitLab must be able to reach your dFlow URL for OAuth callbacks and push webhooks (/api/deploy/gitlab).

4. Use GitLab on an App Service (connected account)Copy Anchor Link

1. Open the Application, choose the Environment, then add or edit an App Service.
2. Open the GitLab tab and choose Connected GitLab account.
3. Select your account, repository, and branch.
4. Save the Service. dFlow registers a project webhook for push events on that branch.
5. Push a commit to the connected branch to trigger a deployment, or deploy manually from the dashboard.

Deployment settingsCopy Anchor Link

For connected GitLab services, open Service Settings to configure:

• Auto Deploy: deploy automatically when new commits are pushed.
• Require Approval Before Deploy: create a pending deployment that must be approved before building.

Commit status badges on GitLab update during the deploy lifecycle (queued, building, success, or failed).

Self-hosted GitLab works the same as gitlab.com after connect: connected-account pickers, automatic webhook registration on save, and the same deployment settings.

Manual deployment (public URL or PAT)Copy Anchor Link

Use this when you are not using a connected OAuth account:

1. Add or edit an App Service and open the GitLab tab.
2. Choose Manual deployment.
3. Enter the repository URL, branch, and optional Git Token for private repos.
4. Deploy or Redeploy when you are ready to build.

To create a PAT: GitLab → Edit profile → Access Tokens. Use at least read_repository for private clone-only deploys.

Permission and access errorsCopy Anchor Link

RelatedCopy Anchor Link

• Git source integrations
• GitHub integration
• App services
• Integration troubleshooting
• Integration issues