Skip to content
Picket

GitLab

Picket can scan GitLab project repository files, group project repositories, merge request source heads, issue bodies and comments, release descriptions and assets, project snippets, job trace logs, job artifact archives, and generic package files through native source enumeration for picket scan.

This is opt-in native source behavior. Workspace scans remain the default because they are deterministic and use normal checkout permissions. Strict Gitleaks-compatible commands are unchanged.

Terminal window
picket scan --gitlab-project willibrandon/picket --gitlab-token-env PICKET_GITLAB_SOURCE_TOKEN --report-format jsonl

Project repository scans resolve the default branch when --gitlab-ref is omitted, list repository blobs through the GitLab repository tree API, and download raw file bytes through the repository files API:

Terminal window
picket scan --gitlab-project willibrandon/picket --gitlab-ref main --gitlab-token-env PICKET_GITLAB_SOURCE_TOKEN --report-format jsonl

Group scans list projects in a GitLab group and scan each project repository:

Terminal window
picket scan --gitlab-group team/platform --gitlab-token-env PICKET_GITLAB_SOURCE_TOKEN --report-format jsonl

Subgroup projects are explicit:

Terminal window
picket scan --gitlab-group team/platform --gitlab-include-subgroups --gitlab-token-env PICKET_GITLAB_SOURCE_TOKEN --report-format jsonl

Merge request scans resolve the merge request source project and source head before listing repository files:

Terminal window
picket scan --gitlab-project willibrandon/picket --gitlab-merge-request 42 --gitlab-token-env PICKET_GITLAB_SOURCE_TOKEN --report-format jsonl

--gitlab-ref and --gitlab-merge-request are mutually exclusive.

Project snippet scans list snippets and download raw snippet content through the GitLab project snippets API:

Terminal window
picket scan --gitlab-project willibrandon/picket --gitlab-include-snippets --gitlab-token-env PICKET_GITLAB_SOURCE_TOKEN --report-format jsonl

Snippet scanning is additive to repository file scanning. It cannot be combined with --gitlab-merge-request.

Project job logs and artifact archives are explicit:

Terminal window
picket scan --gitlab-project willibrandon/picket --gitlab-include-job-logs --gitlab-include-job-artifacts --gitlab-token-env PICKET_GITLAB_SOURCE_TOKEN --report-format jsonl

Job log and artifact scanning is additive to repository file scanning. It cannot be combined with --gitlab-merge-request. Artifact archives use Picket’s archive traversal limits before archive entries become scan targets.

Pipeline-scoped job scans limit job enumeration to one pipeline:

Terminal window
picket scan --gitlab-project willibrandon/picket --gitlab-pipeline-id 123 --gitlab-include-job-logs --gitlab-include-job-artifacts --gitlab-token-env PICKET_GITLAB_SOURCE_TOKEN --report-format jsonl

Pipeline-scoped job scans require --gitlab-project and at least one of --gitlab-include-job-logs or --gitlab-include-job-artifacts.

Generic package file scans are explicit:

Terminal window
picket scan --gitlab-project willibrandon/picket --gitlab-include-packages --gitlab-token-env PICKET_GITLAB_SOURCE_TOKEN --report-format jsonl

Package scanning lists GitLab packages with package_type=generic, lists each package’s files, downloads each file through the generic package registry endpoint, and expands archive package files through Picket’s archive limits. It is additive to project and group repository scans. It cannot be combined with --gitlab-merge-request.

Issue scanning is explicit and includes issue comments:

Terminal window
picket scan --gitlab-project willibrandon/picket --gitlab-include-issues --gitlab-issue-state opened --gitlab-token-env PICKET_GITLAB_SOURCE_TOKEN --report-format jsonl

--gitlab-issue-state accepts all, opened, or closed and defaults to all. Issue descriptions and comments become synthetic Markdown scan targets. Comment requests use GitLab’s activity_filter=only_comments filter so system notes do not become scan targets. Issue scanning is additive to project and group repository scans and cannot be combined with --gitlab-merge-request.

Release descriptions and release assets are independent explicit scopes:

Terminal window
picket scan --gitlab-project willibrandon/picket --gitlab-include-releases --gitlab-include-release-assets --gitlab-token-env PICKET_GITLAB_SOURCE_TOKEN --report-format jsonl

Release descriptions become synthetic Markdown scan targets. Release assets are downloaded from release links returned by GitLab and expanded through Picket’s archive limits when the content is an archive. Either scope can be selected alone. Both are additive to project and group repository scans and cannot be combined with --gitlab-merge-request.

The project selector accepts a namespace path, numeric project ID, or project URL:

Terminal window
picket scan --gitlab-project https://gitlab.com/willibrandon/picket --gitlab-token-env PICKET_GITLAB_SOURCE_TOKEN --report-format jsonl

The token is read from an environment variable and is never passed as a command-line value.

Option Purpose
--gitlab-project Project to scan as a namespace path, numeric project ID, or project URL.
--gitlab-group Group to scan as a namespace path, numeric group ID, or group URL.
--gitlab-ref Optional branch, tag, or commit SHA. Empty uses the project default branch.
--gitlab-merge-request Optional merge request internal ID. Scans the merge request source head.
--gitlab-pipeline-id Optional pipeline ID used to limit job log and artifact enumeration. Requires --gitlab-project and a job source flag.
--gitlab-include-subgroups Include subgroup projects when scanning a group.
--gitlab-include-snippets Include project snippets.
--gitlab-include-job-artifacts Include GitLab job artifact archives.
--gitlab-include-job-logs Include GitLab job trace logs.
--gitlab-include-packages Include GitLab generic package files.
--gitlab-include-issues Include GitLab issue descriptions and comments.
--gitlab-issue-state Select all, opened, or closed issues. Defaults to all and implies issue scanning.
--gitlab-include-releases Include GitLab release descriptions.
--gitlab-include-release-assets Include GitLab release assets.
--gitlab-token-env Environment variable containing the GitLab token.
--gitlab-api-endpoint GitLab API endpoint used for repository enumeration. Defaults to https://gitlab.com/api/v4/.
--allow-non-public-source-endpoints Permit private, loopback, link-local, or otherwise non-public endpoint addresses for self-managed GitLab.
--allow-insecure-source-endpoints Permit HTTP source endpoints for trusted local tests or explicitly accepted self-managed environments; source credentials may be sent in cleartext.

API Flow

Section titled “API Flow”
Source API behavior
Group projects Lists group projects with per_page=100. include_subgroups=true is sent only when --gitlab-include-subgroups is set.
Project metadata Resolves the default branch when --gitlab-ref is omitted.
Merge request metadata Resolves source_project_id and the source ref. Picket prefers diff_refs.head_sha, then sha, then source_branch.
Repository tree Lists blobs recursively with per_page=100 and page-based pagination.
Raw file content Downloads selected file bytes through the raw repository file endpoint.
Project snippets Lists project snippets with per_page=100 and downloads raw snippet content through the project snippets API.
Project jobs Lists project jobs with per_page=100. When requested, downloads job trace logs and artifact archives by job ID.
Pipeline jobs Lists jobs for one project pipeline with per_page=100. When requested, downloads job trace logs and artifact archives by job ID.
Generic package files Lists project packages with package_type=generic and per_page=100, lists package files for each package, and downloads each file through the generic package registry route.
Project issues Lists issues with per_page=100 and the selected state. Issue descriptions become synthetic Markdown.
Issue comments Lists notes with activity_filter=only_comments and per_page=100. Comment bodies become synthetic Markdown.
Project releases Lists releases with per_page=100. Release descriptions become synthetic Markdown.
Release assets Uses embedded release links when available and otherwise lists release links with per_page=100. Downloads and expands selected assets.

Pagination And Limits

Section titled “Pagination And Limits”

Repository tree enumeration follows GitLab pagination while X-Next-Page or a rel="next" link is present. Picket caps REST pagination at 1,000 pages per paged list and emits a warning if that safety limit is reached.

Remote downloads use a 100 decimal MB default cap. --max-target-megabytes overrides that cap with a positive value. Zero keeps its local-scan compatibility meaning, but remote GitLab sources reject zero because remote HTTP bodies are always bounded.

Provider metadata JSON responses are separately capped at 10 decimal MB and skipped with a warning when the cap is exceeded, including responses without a reliable Content-Length.

Oversized tree entries, job artifacts, and package files are skipped before download when GitLab returns a size. Issue, comment, and release-description documents are checked after UTF-8 encoding. Release assets are capped both by Content-Length when present and while streaming.

Job artifact, generic package, and release asset archives use --max-archive-depth, --max-archive-entries, --max-archive-megabytes, and --max-archive-ratio. Archive entries also obey --max-target-megabytes.

Redirect And Credential Safety

Section titled “Redirect And Credential Safety”

Endpoint safety checks run before the first request.

Redirects are disabled before credentials are sent, and responses from injected HTTP handlers that already followed a redirect are rejected instead of scanned. GitLab artifact and package downloads may return signed HTTPS redirects; Picket follows those redirects without forwarding the PRIVATE-TOKEN header and keeps connect-time endpoint guarding active.

Release links may point outside the configured GitLab authority. Picket sends PRIVATE-TOKEN only when the release asset URI has the same scheme, host, and port as the configured API endpoint. External release links and all redirected requests are unauthenticated. Endpoint safety checks, HTTPS policy, one-hop redirect handling, and byte caps still apply.

Picket sends the configured token as a PRIVATE-TOKEN header. It does not send the token as a query string or print it in diagnostics.

Permissions

Section titled “Permissions”

Use the narrowest project or group selection possible. Repository file scanning needs read-only access to project metadata, repository tree entries, and raw repository file content for the selected project. Group scanning also needs read access to the group project listing and to each selected project repository. Merge request scanning needs read access to merge request metadata and the source project when the merge request originates from a fork. Issue and release scanning needs read access to the selected project’s issues, issue notes, releases, and release links. Snippet scanning needs read access to project snippets and raw snippet content. Job log and artifact scanning needs read access to project pipeline metadata when --gitlab-pipeline-id is used, project job metadata, traces, and job artifact archives. Generic package scanning needs read access to package metadata, package file metadata, and package file downloads. Write, maintainer, owner, registry-write, runner, and token-administration scopes are not needed for source enumeration.

References

Section titled “References”
  • GitLab pipelines API: https://docs.gitlab.com/api/pipelines/
  • GitLab repositories API: https://docs.gitlab.com/api/repositories/
  • GitLab groups API: https://docs.gitlab.com/api/groups/
  • GitLab merge requests API: https://docs.gitlab.com/api/merge_requests/
  • GitLab project snippets API: https://docs.gitlab.com/api/project_snippets/
  • GitLab jobs API: https://docs.gitlab.com/api/jobs/
  • GitLab job artifacts API: https://docs.gitlab.com/api/job_artifacts/
  • GitLab packages API: https://docs.gitlab.com/api/packages/
  • GitLab generic packages repository: https://docs.gitlab.com/user/packages/generic_packages/
  • GitLab issues API: https://docs.gitlab.com/api/issues/
  • GitLab notes API: https://docs.gitlab.com/api/notes/
  • GitLab releases API: https://docs.gitlab.com/api/releases/
  • GitLab release links API: https://docs.gitlab.com/api/releases/links/
  • GitLab repository files API: https://docs.gitlab.com/api/repository_files/
  • GitLab REST pagination: https://docs.gitlab.com/api/rest/#pagination