Security works through Coroid's GitHub App. This page lists what the App needs
for Security, what the Coroid Security check reports, how to make GitHub
require it, and how GitHub's own security alerts appear in Security.
Permissions
Security uses the permissions the App already has for your repositories: reading code and pull requests, and writing checks. These are optional, and each adds one thing:
| Permission | What it adds | Without it |
|---|---|---|
| Merge queues: read-only, with the Merge group event | Coroid Security on merge queue commits | Merge queues get no Coroid Security result |
| Dependabot alerts: read-only, with its event | Imports Dependabot alerts | Not imported |
| Code scanning alerts: read-only, with its event | Imports GitHub code scanning alerts | Not imported |
| Secret scanning alerts: read-only, with its event | Imports GitHub secret scanning alerts, without the secret values | Not imported |
When the App asks for a new permission, GitHub asks your organization's owner to accept it for your installation. Until then, Security → Overview says which repositories lack it, with a link to the installation on GitHub.
Coroid also reads whether each repository is public or private, from GitHub's events and by asking GitHub, to decide what may be published there. See Disclosure.
The Coroid Security check
Coroid Security is one check, with one name, whether it runs on its own or as
part of the project's Delivery graph in Quality Control, so a repository can
require it once. It reports the protections that check each change:
Vulnerable dependencies and Leaked secrets. The worse of the two decides.
Code scanning reports through Quality Control's checks, and Security review
through the Coroid Review check.
It runs on GitHub repositories connected through the App:
- when a pull request is opened, reopened, updated or marked ready for review;
- on each merge queue commit, with the Merge queues permission;
- when someone re-runs it on GitHub.
It appears as in progress as soon as the event arrives. Its details link opens the project in Security.
What it reports
| State | Enforced | Observe only |
|---|---|---|
| Complete coverage of the change, nothing at or above the threshold | Success | Success |
| A finding at or above the threshold | Failure | Neutral, naming it |
| The scan failed or could not run, a file the change touches is only partly covered, or the configuration could not be read | Failure, saying why and how to re-run | Neutral, saying why |
| No result within 10 minutes | Failure, "timed out" | Neutral |
| Every protection off for the project | Neutral | Neutral |
It is never "skipped": GitHub counts a skipped required check as passing, so an enforced protection that did not run would read as a pass. A required check always gets one of the results above, so a merge queue never waits forever.
The check counts only what the change introduces, not findings already on the base branch. Its text never names a finding that is not public; it says how many it found, at what threshold, and that the details are in Coroid.
Require the Coroid Security check
Enforcing a protection makes the check fail. GitHub blocks the merge only if the repository requires the check:
- Branch protection: in the repository's Settings → Branches, edit the rule
for your default branch, turn on Require status checks to pass before
merging, and add
Coroid Security. - Rulesets: in Settings → Rules → Rulesets, add Require status checks to
pass to the ruleset for your default branch, add
Coroid Security, and choose Coroid's GitHub App as its source. - Merge queues: require the check in the same rule. The App needs the Merge queues permission so the check runs on merge queue commits.
Require it once the protections you want to enforce are enforcing. A required check that only observes still passes.
GitHub security alerts
With GitHub security alerts on in Security → Settings and the permissions above, Security imports Dependabot, code scanning and secret scanning alerts as observations on the same findings Coroid's own scans produce. New alerts arrive as GitHub sends them, and Coroid reads each repository's alerts again once a day.
- Imported, not confirmed. An alert that Coroid's own scans have not confirmed shows "Imported from GitHub, not confirmed yet". It is listed and counted, and does not notify or block until Coroid's scan confirms it.
- Sources disagree. When GitHub and Coroid report a finding differently, the finding says so and shows each source's state: present, gone, dismissed, or could not be read.
- Each source closes in its own way. A Dependabot alert is fixed on GitHub when the default branch no longer has the vulnerable version. A code scanning alert is fixed when analysis of the default branch stops reporting it. A secret scanning alert stays open until someone resolves it on GitHub, so merging a fix does not close it.
- Lost permission. If the App loses a permission or GitHub turns a feature off, findings that only that source reported show "status unknown since" that time, and nothing closes.
Overview shows, per repository and source, whether its alerts were read, the permission is missing, the feature is off on GitHub, or the repository could not be reached.