GitLab source sync

Connect and import

You need administrator access to the Composal organization and Maintainer or Owner access to the GitLab project. The selected GitLab branch must contain a commit and allow you to push.

1. In Composal, choose New Repo → Connect Repos. Choose a connected GitHub or GitLab account.
2. If your account is missing, choose Add GitHub Account or Add GitLab Account, complete authorization, then select the account.
3. Select up to 30 GitLab repositories and choose Connect Repos. Selections stay selected across searches and pages. The default branch is selected automatically. Use the options button beside a selected repository to choose another branch or exclude the Repo from Home.
4. Follow the import progress, then open a connected Repo or use the displayed commands to clone it. Reloading the progress page preserves the import you are viewing.

GitLab OAuth grants the api scope to discover projects, configure push webhooks, and read and write Git data. Its permissions follow the authorizing GitLab account. Composal synchronizes only projects you explicitly import into the organization.

Work in either repository

Changes pushed to the selected GitLab branch are imported automatically. Changes landed or pushed to the corresponding Composal trunk are projected back to GitLab. Unlanded Composal Changes are not published as GitLab merge requests.

Import GitLab repositories through the browser. Local-assisted com repo import currently supports GitHub only and directs unsupported imports back to your organization’s browser picker.

Use the ordinary Composal clone and Change workflow after import. Native commit identities are retained when projected commits return from GitLab. Composal checks the expected remote head before pushing and does not force-push over an unexpected update.

The connection view shows the mapped branch, last synchronization time, and failures. Webhooks provide prompt updates; periodic reconciliation recovers missed events.

Manage synchronization

Open Connect Repos, choose the GitLab account, then expand Manage Connected Repos below the repository picker:

• Retry Import resumes a failed import without creating another Repo.
• Sync Now requests reconciliation after a temporary failure.
• Pause stops automatic sync. Resume Sync checks access again before enabling it.
• Disconnect preserves the Composal Repo and history and removes Composal's project webhook. Resume recreates the webhook.
• Connect or Reconnect GitLab renews authorization. To use another authorized account, select that account and choose Use Selected GitLab Account on the Repo.
• While paused, Change Branch remaps the GitLab source. Both GitLab branches must point to the same commit first; the Composal trunk stays unchanged. A GitLab default-branch change never silently remaps a connection.

If a protected branch rejects a push, correct its permissions in GitLab and retry. For divergence, inspect and reconcile the two histories before retrying. A deleted source branch pauses the connection when its webhook is received; restore it before resuming. Composal does not propagate branch deletions.

Supported scope

This integration supports GitLab.com and one selected branch per project. It imports the source tree and history reachable from that branch. Other branches, tags, merge requests, issues, pipelines, LFS object bytes, and recursive submodule repositories are outside this release. Tracked LFS pointers and gitlinks remain source data; their external contents need separate access.

GitLab import starts in the browser. The local-assisted com repo import flow remains GitHub-specific. Continue with Composal source control and Changes and stacking for everyday work.