Skip to main content
Cortex Security reviews pull requests through a GitHub App that you install on the repositories you choose. This page is about that installation: what the App asks GitHub for and why, how the repositories list works, where the review policy lives, what Security mode adds, and how to stop reviews at four different levels without guessing which one you want. For the walk-through that gets you from nothing to a first reviewed pull request, read the Security quickstart instead. Everything here is the reference behind it, on the App tab of Cortex Security.

​
Two GitHub connections, and neither implies the other

This is the single most common confusion, and the install page carries an inline explainer about exactly it. Three separate things touch GitHub, and reaching for the wrong one is the usual cause of “why is nothing being reviewed”. The two connections coexist happily, and installing one does not install the other. Use whichever fits, or both.

​
Installing and claiming the installation

Choose Install on GitHub under Install Cortex Security on GitHub, pick the repositories GitHub should let it see, and confirm. GitHub sends you back to the App tab, which claims the new installation; the server confirms it against GitHub before storing it, so nobody can claim an installation by editing a query parameter. A toast reads GitHub connected, or Could not connect GitHub when the claim did not work.
Self-hosting a deployment adds one requirement: the App’s Setup URL has to point at this install page, because GitHub only hands back the installation identifier when it does. The page tells you the exact URL to register: After install, GitHub must send people to . Register that as the App’s Setup URL.

​
What the App asks for

The page lists what it asks for under WHAT THE APP ASKS FOR, with a reason beside each one. The full set the App requests is five permissions, and nothing beyond them. Commit statuses is requested as read-only and is not used today, and would only matter if you wanted the App to read other checks. Nothing else. In particular not Administration, not Actions, and not Secrets. The App listens for five kinds of event: pull request, issue comment, installation, installation repositories, and pull request review thread. Two of those are worth knowing about, because an installation that does not receive them looks broken rather than unsubscribed: issue comment is what makes mentioning the App work at all, and pull request review thread is how resolving one of its comment threads counts as a dismissal.

​
The repositories list

Under REPOSITORIES each repository the installation can see has its own switch, labelled Review pull requests in {name}. A repository that is off gets no review, no comment and no check run: nothing at all reaches its pull requests. Each row also shows how many pull requests Cortex Security has seen there, or No pull requests seen yet, and marks a Private repository as such. Two more controls sit around the list.
  • Review new repositories automatically: When a repository is added to the installation later, start reviewing its pull requests without asking. Off means it arrives switched off and you enable it here. This is the setting behind “I added a repository and nothing happened”.
  • Add or remove repositories on GitHub takes you to GitHub, which owns the list of repositories the App can see at all. When there are none, the page says The installation has no repositories yet. Add some on GitHub and they will appear here.
Under CONNECTION the state reads Connected once an installation is claimed.

​
Where the review policy lives

The review policy is set once, on the Policy tab, and governs the installation, which means every repository in it. There is no per-repository policy screen today: if you need different treatment per repository, the levers are the repository switch above and a file in the repository itself. A repository can carry its own instructions and rules on the branch under review. Those can make a review stricter or better informed, and they cannot exclude a path, raise a threshold or switch the review off, because the author of a pull request would otherwise have a say over the scrutiny it receives. Review policy covers both layers and what each may change.

​
Security mode

Security mode is the switch that enables repository scans. It is separate from the installation, and the two only meet when you start a scan.
  • Turning the mode on does not need the GitHub App. Starting a scan does, on a repository this account owns.
  • A personal enable is ungated. An organisation-wide enable needs an owner or an admin and an Enterprise plan, after which members inherit it and need no switch of their own. An admin who enables the organisation keeps their personal switch as well. See Plans.
  • GitHub.com only: GitHub Enterprise Server is not available yet.
Repository scans covers what the mode unlocks.

​
States you may see

Cortex Security is not available to guest accounts, and a guest trying to install the App is refused with the reason: a guest session cannot be signed back into later in order to revoke a GitHub installation.

​
Stop reviews

Four different levels, and people habitually reach for the wrong one.