Skip to main content
Once a repository is connected, you can scan it on demand. Connecting a repository doesn’t start a scan by itself.
1

Start a new scan

Click New Scan in the sidebar and pick the repository, or open the repository from Repositories and start a scan there.
2

Scan the default branch

Run a deep scan on the branch your team trusts as the baseline (usually main). Keep the first run simple: one repository, one branch. You can add related repositories later for a multi-repo scan.
3

Wait for the pipeline to finish

Gecko generates the wiki, indexes the code, discovers endpoints, and analyzes security-sensitive files. Progress is shown on the scan.
4

Review results

Open the Findings tab to triage findings, the Endpoints tab for the attack surface, and the Wiki tab for the codebase overview. See Findings & remediation.

Run a scan from the API

Trigger the same scan from a script, a CI job, or a developer machine with POST /scans. Use an API key with the scans.run permission.
  • commit pins the scan to one commit, full or abbreviated SHA. Without it, Gecko scans the tip of branch at launch.
  • branch labels the scan. Without commit, it also picks what to scan. If you leave it out, Gecko uses the repository’s default branch.
  • The commit must already be pushed. If it isn’t, the request fails with 400 commit_not_found.
  • A pinned scan is a deep scan of the repository at that commit, not a scan of the diff.
The response returns the scan id. Poll GET /scans/{id} or subscribe to webhooks to know when results are ready.

Scan several repositories

Send repository_ids instead of repository to cover up to 100 connected repositories in one scan. Each request takes one of the two fields, not both. Get the IDs from GET /repositories.
  • Gecko creates one scan, and it counts once against your plan’s scan limit.
  • branch applies to every repository. If you leave it out, Gecko scans each repository’s default branch.
  • You can’t send commit, base_commit, or provider with repository_ids.
  • Every ID must be a connected repository your API key can access. If one isn’t, the request fails with 400 repository_not_connected and Gecko creates no scan.
  • All repositories in a scan must use the same provider. A request that mixes GitHub and GitLab fails with 400 mixed_repository_providers, so start one scan per provider.
  • The first ID is the scan’s primary repository, and the repository field in the response names it.
If a repository can’t be checked out, for example because it has no branch matching branch, Gecko skips it, scans the rest, and records the skip on the scan.

Scan it again

Scanning the same branch again updates existing findings instead of creating duplicates, and with fix detection on it closes the ones you’ve fixed. See Re-scans and fix detection. To scan on a cadence, set up a scheduled scan. For the order to turn things on across many repositories, see the rollout plan.

Repository views

Each repository has tabs for Overview, Findings, Endpoints, Wiki, Scans, and Settings, so you can move between the latest results and historical scans in one place.