GitLab importing

← All articles

Connect a GitLab project so lockfile changes import automatically on every push. SourceTrust watches the chosen branches and applies the resolved inventory.

For reconnect, keep the same repository authority and Production and optional Testing selections. Retained extra watched branches are included automatically, preserving their inventory, reviews and comments. A different repository or changed Production or Testing selection is refused.

If a previously synced branch cannot be read, its inventory stays visible and a branch-specific Sync issue needs attention. Restore the branch or repository access and run Re-sync. Restoring the same commit also recovers a completed empty inventory without losing removal evidence. The warning clears only after all connected branches are healthy. If the branch was deliberately retired, change or remove Testing or the watched branch in project settings, or select an existing valid Production slot. Reconnecting with different branch roles is not supported.

Instead of uploading a file by hand, connect one GitLab project per SourceTrust project. When someone pushes to the watched branch, SourceTrust fetches the lockfile, imports new and updated dependencies automatically, and marks them Needs review. A package that disappears from the lockfile is flagged Removed (kept for review, never deleted silently). Removed packages cannot be approved; resolve them with Remove from inventory in the Review walkthrough or on the package page, or publishing the page also drops packages that had left the lockfile. There is no separate preview or apply step.

Setup

In GitLab, open the target project → Settings → Access Tokens.
Create a Project Access Token with role Maintainer and scope api. Maintainer is required so SourceTrust can create the project webhook. Copy the token - GitLab shows it once.
Open the project in SourceTrust → Settings → connect a repository → GitLab, and paste the token.
Pick your GitLab project from the list, then choose your Production branch (feeds the public attestation page) and, optionally, turn on Watch a testing branch (internal review only). Both sync on connect and on push. You can change or remove Testing later in project settings.
On the first repository connection, any manually uploaded Production and Testing inventory is permanently deleted, including review decisions, pasted license text, obligation acknowledgements, vulnerability findings and acknowledgements, and package comments. Manual upload is disabled while connected. Disconnecting or a failed initial sync cannot restore the deleted upload work. Published attestation history remains unchanged.

Group Access Tokens work the same way as Project Access Tokens if you prefer to manage the token at the group level.

Every push to a watched branch checks all discovered lockfiles, including changes outside the primary file, newly added lockfiles, and documentation-only pushes. SourceTrust still reads and checks the files when the inventory is unchanged, but creates no duplicate inventory change. New or changed packages need review, and the public page changes only when you publish the reviewed inventory.

Auto-discovered lockfiles

Supported files still import when other repository inputs are malformed, unreadable, too large, or binary bun.lockb files. Coverage stays partial and the warning names rejected files, with a summary when details are omitted. If every input is rejected, an established connection reports the cause and keeps the previous inventory. Fix or trim the named repository files, commit Bun’s text bun.lock instead of bun.lockb where needed, then run Re-sync. Disconnect first if you want to upload manually. An initial Connect with no usable dependencies stays unconnected; fix the files and Connect again or upload a supported file manually.

GitLab sync recursively scans your entire repository tree (not just the root) and imports every supported lockfile it finds into one inventory, up to 25 lockfiles per project. Common non-source folders (node_modules, vendor, dist, build, and similar) are skipped automatically. CycloneDX and SPDX SBOM files are not auto-discovered (upload manually or set an explicit lockfilePath).

For format details and direct-vs-transitive rules, see Help center → Manual importing (Manual importing).

Merge requests can receive informational dependency notes comparing the source and target branch lockfiles. Inventory changes only happen on pushes to watched branches. Pushes with zero dependency changes are silent. See Help center → Production vs Testing branches (Production vs Testing branches).

If the connection breaks

For a package metadata-limit error, see Help center → Manual importing (Manual importing) for the supported scope and license-claim limits. Correct the input or contact support with the filename before running Re-sync; retrying unchanged metadata cannot resolve the failure.

A connection can stop working without anyone touching SourceTrust: the access token is revoked or expires, the project webhook is deleted or GitLab disables it after repeated failed deliveries, or a sync starts failing (for example an unsupported or oversized lockfile). GitLab does not push a notification when a token is revoked, so SourceTrust actively re-checks every connected GitLab project about twice a day - for this integration, that check is the primary way a broken connection is discovered, not just a backup. When it finds a problem, the Projects overview shows a Needs your attention banner and a Sync issue badge on the affected project, the project's Settings GitLab card switches to an Error status with the cause, and your organization's notification recipients get an email (at most one per connection per day).

GitLab access tokens expire (up to 365 days). When your token is within 14 days of expiring, the GitLab card in project settings shows a Token expiring warning and SourceTrust sends a warning email. Normally, update the token there before sync stops; your branches and discovered lockfiles are kept. If SourceTrust says the stored webhook credential cannot be decrypted, reconnect the same GitLab project instead.
Reconnecting (or renewing the token) from project settings resumes syncing. Your inventory and finished reviews are unaffected while the connection is down.
If Connect finds no supported lockfile or finds one that is too large, SourceTrust creates no project connection or webhook. Choose a different repository in the same Connect flow, upload the file manually, or fix the repository and run Connect again.
A project stays with the repository it first synced. To use a different repository or provider, create a new project. This protects finished reviews and comments.
Disconnecting a project yourself is silent: no banner, no email. Only connections GitLab or SourceTrust's own checks found broken raise alerts.
If the connection is gone for good, disconnect it from the project's GitLab settings card. That stops the reminders, and you can reconnect the same GitLab project any time.
An unsupported dependency-file version stops the whole sync and keeps your previous inventory visible. Bun text versions 0, 1 and 2 are supported; version 3 is not. For an established connection, fix the file and push the change, wait for the next scheduled check, or run Re-sync. The warning clears when the latest scan for every connected branch succeeds. If the first connection failed, fix the file and run Connect again.
If a received push overlaps inventory verification or a review change, SourceTrust retries automatically after a delay. Your previous inventory stays visible while it retries. If all attempts fail, the project shows a Sync issue. Run Re-sync from project settings after the competing changes settle. A delayed result from an older import does not hide the failure.