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:- 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.
- Gecko scanner → GitHub. Clones the selected repositories over HTTPS at scan time, authenticated with a short-lived installation token.
- 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:- The repository list is populated in Gecko. The App is installed on the right organization and can see the repositories.
- A baseline scan completes on one repository. Cloning works.
- 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.
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 withGET /vulnerabilities/sarif,
then upload the file to GitHub code scanning from your CI. See
SARIF export.
Troubleshooting
FAQ
Do we need to create a webhook or a token?
Do we need to create a webhook or a token?
No. The App carries its own webhook, and Gecko mints short-lived
installation tokens as it needs them. Nothing to paste, nothing to
rotate.
Can we limit Gecko to a few repositories?
Can we limit Gecko to a few repositories?
Yes. Choose Only select repositories when you install, or change the
selection at any time from the App’s Configure page in GitHub.
Does Gecko store our source code?
Does Gecko store our source code?
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.
Do you support GitHub Enterprise Server?
Do you support GitHub Enterprise Server?
Not today. Gecko supports GitHub.com, including organizations on GitHub
Enterprise Cloud. Contact us if you run GitHub Enterprise Server.