Skip to main content
Gecko connects to GitHub.com through the Gecko GitHub App. You install the App on your organization, choose which repositories it can see, and Gecko uses it to list repositories, clone code for scans, post pull request checks and reviews, and open fix pull requests. GitHub.com is a cloud service reachable from anywhere, so there is no network setup: no IP allowlisting, no firewall changes, no personal access token, and no webhook to add by hand. Connecting takes a few minutes.

Before you start

You need:
  • In GitHub: permission to install GitHub Apps on the organization, which usually means an organization owner. A member without it can still start the install; GitHub then sends the request to an owner to approve.
  • In Gecko: admin access to Settings.

How the integration works

Two Gecko components talk to GitHub.com, and GitHub sends events back to Gecko:
  1. Gecko frontend → GitHub API. Syncs the repositories the App can see, reads branches and pull request metadata, posts check runs and review comments, and opens fix pull requests.
  2. Gecko scanner → GitHub. Clones the selected repositories over HTTPS at scan time, authenticated with a short-lived installation token.
  3. GitHub → Gecko. The App’s webhook notifies Gecko when a pull request opens or updates, and when the installation or its repository selection changes, so PR checks and the repository list stay current without polling.

Connect

1

Start the install from Gecko

Go to Settings > Integrations and click Connect on GitHub under Source Control. Gecko redirects you to GitHub to install the Gecko App.
2

Choose repositories on GitHub

Pick the organization, then select All repositories or Only select repositories. GitHub shows the permissions the App requests on this screen. You can change the repository selection later in GitHub without touching Gecko.
3

Return to Gecko

GitHub redirects back and Gecko records the installation for your team. The repositories the App can see sync into the dashboard.
4

Scan

Open a repository and run a baseline scan. To scan pull requests, turn on PR Scanning for the repository. See PR checks.

Verify the connection

You’re done when all three of these are true, in order:
  1. The repository list is populated in Gecko. The App is installed on the right organization and can see the repositories.
  2. A baseline scan completes on one repository. Cloning works.
  3. A test pull request gets a Gecko review. Turn on PR Scanning for the repository, open a draft pull request that touches any file, and look for the Gecko Security Review check. If nothing appears, open the App’s Advanced tab in your organization’s GitHub App settings and check Recent Deliveries for a 200.

What happens on every pull request

When PR scanning is on for a repository, each pull request goes through the same steps:
  • Check run. Gecko posts a Gecko Security Review check. With PR Status Checks on, it fails when the scan finds an issue at or above your Minimum severity to fail. Make it a required check in your branch protection rules to block merges.
  • Review. A review comment summarizes the change and lists findings the pull request introduces, separately from pre-existing ones.
  • Fixes. Commit & Push Fix to PR adds Gecko’s patch as a commit on the pull request branch. See Auto-fix PRs.
Which events trigger a rescan, and what the review includes, are set in Settings > Pull Requests. See Configure PR behavior.

Who sees what

The App installation is a team-level connection: it decides which repositories exist in Gecko and authors every check run, review, and fix pull request. What each dashboard user sees is personal. When your team turns on Settings > Members > Enforce GitHub/GitLab permissions, Gecko shows each user only the synced repositories their own GitHub account can push to. They link that account by signing in with GitHub, or by clicking Connect next to GitHub in Settings > General > Personal connections. Without enforcement, every member sees every synced repository. Developers who only read pull request reviews never need a Gecko account. See How identity works in Gecko.

What the App can access

  • Repositories: only the ones you selected at install time. Removing a repository from the App’s selection removes Gecko’s access to it.
  • Credentials: Gecko never holds a long-lived token. It mints a short-lived installation token for each operation, which GitHub expires automatically, so there is nothing to rotate.
  • Permissions: the exact list is shown on GitHub’s install screen and on the App’s page in your organization settings. If Gecko later requests a new permission, GitHub asks an organization owner to approve it, and Gecko shows a banner until the request is accepted.

Change or remove access

  • Change repositories: in GitHub, go to your organization’s Settings > GitHub Apps, click Configure next to Gecko, and edit the repository selection. Gecko picks up the change from the installation webhook.
  • Suspend or uninstall: from the same page. Gecko stops syncing, scanning, and posting to GitHub, and shows a banner that the GitHub App connection is broken. Your scan history and findings stay in Gecko. Reinstall the App to reconnect.

Export findings to GitHub code scanning

Export findings as SARIF from the app or with GET /vulnerabilities/sarif, then upload the file to GitHub code scanning from your CI. See SARIF export.

Troubleshooting

FAQ

No. The App carries its own webhook, and Gecko mints short-lived installation tokens as it needs them. Nothing to paste, nothing to rotate.
Yes. Choose Only select repositories when you install, or change the selection at any time from the App’s Configure page in GitHub.
Code is cloned for the duration of a scan and not retained. Gecko stores findings with minimal metadata: repository names, usernames/emails, and short (~5–6 line) code snippets. See Architecture.
Not today. Gecko supports GitHub.com, including organizations on GitHub Enterprise Cloud. Contact us if you run GitHub Enterprise Server.