GitLab
Picket can scan GitLab project repository files, group project repositories, merge request source heads, project snippets, pipeline-scoped job trace logs, pipeline-scoped job artifact archives, project job trace logs, project 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.
picket scan --gitlab-project willibrandon/picket --gitlab-token-env PICKET_GITLAB_SOURCE_TOKEN --report-format jsonlProject 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:
picket scan --gitlab-project willibrandon/picket --gitlab-ref main --gitlab-token-env PICKET_GITLAB_SOURCE_TOKEN --report-format jsonlGroup scans list projects in a GitLab group and scan each project repository:
picket scan --gitlab-group team/platform --gitlab-token-env PICKET_GITLAB_SOURCE_TOKEN --report-format jsonlSubgroup projects are explicit:
picket scan --gitlab-group team/platform --gitlab-include-subgroups --gitlab-token-env PICKET_GITLAB_SOURCE_TOKEN --report-format jsonlMerge request scans resolve the merge request source project and source head before listing repository files:
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:
picket scan --gitlab-project willibrandon/picket --gitlab-include-snippets --gitlab-token-env PICKET_GITLAB_SOURCE_TOKEN --report-format jsonlSnippet scanning is additive to repository file scanning. It cannot be combined with --gitlab-merge-request.
Project job logs and artifact archives are explicit:
picket scan --gitlab-project willibrandon/picket --gitlab-include-job-logs --gitlab-include-job-artifacts --gitlab-token-env PICKET_GITLAB_SOURCE_TOKEN --report-format jsonlJob 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:
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 jsonlPipeline-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:
picket scan --gitlab-project willibrandon/picket --gitlab-include-packages --gitlab-token-env PICKET_GITLAB_SOURCE_TOKEN --report-format jsonlPackage 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.
The project selector accepts a namespace path, numeric project ID, or project URL:
picket scan --gitlab-project https://gitlab.com/willibrandon/picket --gitlab-token-env PICKET_GITLAB_SOURCE_TOKEN --report-format jsonlThe 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-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. |
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.
Job artifact and generic package 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.
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. 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 repository files API:
https://docs.gitlab.com/api/repository_files/ - GitLab REST pagination:
https://docs.gitlab.com/api/rest/#pagination