GitHub

Picket’s GitHub support has two native layers:

• repository source enumeration for picket scan,
• hosted GitHub Secret Protection alert capture for parity analysis.

Neither layer changes strict Gitleaks-compatible commands.

Repository And Gist Source Scanning

GitHub repository and gist enumeration is opt-in native source behavior. Workspace scans remain the default because they are deterministic and use normal checkout permissions.

picket scan --github-repository willibrandon/picket --github-token-env PICKET_GITHUB_SOURCE_TOKEN --report-format jsonl

Pull request scans resolve the head repository and commit before enumerating files:

picket scan --github-repository willibrandon/picket --github-pull-request 42 --github-token-env PICKET_GITHUB_SOURCE_TOKEN --report-format jsonl

Release scans read release bodies and release assets:

picket scan --github-repository willibrandon/picket --github-include-releases --github-token-env PICKET_GITHUB_SOURCE_TOKEN --report-format jsonl

Actions artifact scans read artifact ZIP entries through the same archive safety caps used by native filesystem scans:

picket scan --github-repository willibrandon/picket --github-include-actions-artifacts --github-token-env PICKET_GITHUB_SOURCE_TOKEN --report-format jsonl

Issue scans read issue bodies and issue comments. Pull requests returned by GitHub’s Issues API are skipped because pull request source is scanned through --github-pull-request.

picket scan --github-repository willibrandon/picket --github-include-issues --github-issue-state all --github-token-env PICKET_GITHUB_SOURCE_TOKEN --report-format jsonl

Organization scans enumerate repositories visible to the token and then scan each selected repository:

picket scan --github-organization willibrandon --github-repository-type sources --github-token-env PICKET_GITHUB_SOURCE_TOKEN --report-format jsonl

User scans enumerate public repositories for the selected login and then scan each selected repository:

picket scan --github-user octocat --github-repository-type owner --github-token-env PICKET_GITHUB_SOURCE_TOKEN --report-format jsonl

Gist scans can target one gist, the authenticated user’s gists, or a user’s public gists. Gist files and gist comments are scanned.

picket scan --github-gist 0123456789abcdef --github-token-env PICKET_GITHUB_SOURCE_TOKEN --report-format jsonl
picket scan --github-gists --github-token-env PICKET_GITHUB_SOURCE_TOKEN --report-format jsonl
picket scan --github-user-gists octocat --github-token-env PICKET_GITHUB_SOURCE_TOKEN --report-format jsonl

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

Option	Purpose
--github-repository	Repository to scan as owner/name or a GitHub repository URL.
--github-organization	Organization login whose visible repositories should be scanned.
--github-user	User login whose public repositories should be scanned.
--github-repository-type	Repository listing filter. Organization scans accept all, public, private, forks, sources, or member. User scans accept all, owner, or member. Empty uses all.
--github-gist	Single gist identifier to scan.
--github-gists	Include the authenticated user’s gists.
--github-user-gists	Include public gists for the specified GitHub user login.
--github-token-env	Environment variable containing the GitHub token.
--github-ref	Optional branch, tag, or commit SHA. Empty uses each repository’s default branch.
--github-pull-request	Pull request number whose head repository and SHA should be scanned. Requires --github-repository and cannot be combined with --github-ref.
--github-include-issues	Include GitHub issue bodies and issue comments. Cannot be combined with --github-pull-request.
--github-issue-state	Issue state filter: open, closed, or all. Supplying this option enables issue enumeration.
--github-include-releases	Include GitHub release bodies and release assets. Cannot be combined with --github-pull-request.
--github-include-actions-artifacts	Include GitHub Actions artifact ZIP contents. Cannot be combined with --github-pull-request.
--github-source-api-endpoint	GitHub API endpoint used for repository enumeration.
--github-api-endpoint	Shared GitHub API endpoint used when a source-specific endpoint is not supplied.
--allow-non-public-source-endpoints	Permit private, loopback, link-local, or otherwise non-public endpoint addresses for GitHub Enterprise Server.
--allow-insecure-source-endpoints	Permit HTTP source endpoints for trusted local tests or explicitly accepted self-hosted environments; source credentials may be sent in cleartext.

GitHub API Flow

Source	API behavior
Repository files	Resolves the default branch through the repository metadata API, lists blobs through the recursive Git Trees API, and downloads bytes through the raw Contents API.
Pull requests	Resolves head.sha and head.repo.full_name through the pull request REST API, then scans that commit in the returned head repository, including forks when GitHub returns them.
Releases	Uses the releases REST API with per_page=100, scans release body text as synthetic Markdown, scans listed release assets, and falls back to the release-assets API when an asset list is not embedded.
Actions artifacts	Uses the repository Actions artifacts API with per_page=100, downloads artifact ZIP archives through GitHub’s short-lived redirect, and expands entries with --max-archive-depth, --max-archive-entries, --max-archive-megabytes, --max-archive-ratio, and --max-target-megabytes.
Issues	Uses the repository Issues API with per_page=100, skips entries that contain a pull_request marker, and reads issue comments through the issue comments API.
Organization repositories	Uses the list organization repositories REST API with per_page=100.
User repositories	Uses the list repositories for a user REST API with per_page=100.
Gists	Uses the authenticated-user, user-public, and single-gist REST APIs.

Pagination And Limits

Repository-listing modes follow GitHub’s Link pagination header while a rel="next" page 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 GitHub 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 and Actions artifact ZIPs are skipped before download when GitHub returns a size. Oversized issue, comment, release, and gist synthetic files are skipped before scanning.

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.

Release asset requests use Accept: application/octet-stream and handle GitHub 200 or 3xx responses. Redirected release asset downloads are fetched without forwarding the bearer token.

Actions artifact ZIP redirects are fetched without forwarding the bearer token.

Gist raw downloads use raw_url without forwarding the bearer token to the raw host.

Gist Details

Picket fetches each selected gist detail before scanning files. It warns when GitHub reports a truncated file list, scans inline gist file content when available, and scans gist comments through the gist comments API.

Failure Handling

Repository tree truncation and per-file download failures are warnings. Organization and user scans also treat per-repository tree failures as warnings and continue with the remaining repositories.

A single-repository scan still fails when the selected repository tree cannot be read.

The current scope is single-repository file enumeration, repository pull request head enumeration, repository, organization, and user issue body/comment enumeration, repository, organization, and user release body/asset enumeration, repository, organization, and user Actions artifact enumeration, organization repository discovery, public user repository discovery, single gist scans, authenticated-user gist scans, and public user gist scans. Packages and code-search-backed discovery remain planned explicit opt-ins.

Recommended fine-grained token permissions for repository file enumeration are:

Permission	Access
Metadata	Read
Contents	Read, including release body and release asset enumeration
Actions	Read, only when --github-include-actions-artifacts is used
Pull requests	Read, only when --github-pull-request is used
Issues	Read, only when --github-include-issues or --github-issue-state is used
Gists	Fine-grained tokens do not require repository permissions for read-only gist APIs; classic OAuth tokens use the gist scope for private user gists

Use the narrowest repository selection possible. Organization scans require access to list the organization repositories selected by --github-repository-type; the same token also needs Contents Read on repositories whose files should be scanned. User scans use GitHub’s public user repository listing and need Contents Read for repositories whose files should be scanned. Pull request scans need Pull Requests Read on the base repository and Contents Read on the head repository. Issue scans need Issues Read on repositories whose issue bodies and comments should be scanned. Gist scans need only the read access required by GitHub’s gist APIs for the selected gist scope. Write, administration, workflow, security-event write, and secret-scanning alert permissions are not needed for repository or gist source enumeration.

Hosted Alert Oracle

GitHub Secret Protection secret scanning is proprietary hosted behavior, so Picket treats it as an alert oracle rather than an implementation reference. scripts/Capture-GitHubSecretScanningOracle.cs captures sanitized alert metadata through gh api; it does not write raw secret values. scripts/Compare-GitHubSecretScanningOracle.cs compares a native Picket JSONL report to the sanitized alert metadata by mapped alert type and location.

The manual Live GitHub Secret Scanning Oracle workflow uses PICKET_GITHUB_SECRET_SCANNING_PAT to capture alerts for willibrandon/picket by default, optionally compares them to a redacted native git-history scan of the checkout, and uploads sanitized artifacts.

Recommended fine-grained token permissions for hosted alert capture are:

Permission	Access
Metadata	Read
Secret scanning alerts	Read

This token is separate from source-enumeration tokens. It should not have write, administration, workflow, or code-scanning upload permissions.

Official API references:

• GitHub repository metadata REST API: https://docs.github.com/rest/repos/repos
• GitHub pull requests REST API: https://docs.github.com/rest/pulls/pulls
• GitHub issues REST API: https://docs.github.com/rest/issues/issues
• GitHub issue comments REST API: https://docs.github.com/rest/issues/comments
• GitHub gists REST API: https://docs.github.com/rest/gists/gists
• GitHub gist comments REST API: https://docs.github.com/rest/gists/comments
• GitHub releases REST API: https://docs.github.com/rest/releases/releases
• GitHub release assets REST API: https://docs.github.com/rest/releases/assets
• GitHub Actions artifacts REST API: https://docs.github.com/rest/actions/artifacts
• GitHub REST pagination: https://docs.github.com/en/rest/using-the-rest-api/using-pagination-in-the-rest-api
• Git trees REST API: https://docs.github.com/v3/git/trees
• Repository contents REST API: https://docs.github.com/en/rest/repos/contents
• Secret scanning alert REST API: https://docs.github.com/en/rest/secret-scanning/secret-scanning