GitHub
Last updated
Was this helpful?
Last updated
Was this helpful?
is a Git-based source code repository. You can use GitHub to share code with team members, track and manage changes to code over time, and collaborate on projects across your organization.
Integrating GitHub with Cortex allows you to:
Automatically discover and track ownership of GitHub entities
Follow a GitOps workflow with GitHub to manage your Cortex workspace
View information about your GitHub repositories on an , including: The repo associated with the entity, recent commits and releases in the event timeline, the most-used language in the files for that entity, the top code contributors, and their number of contributions.
In an entity's Code & Security section, see vulnerabilities from (Code scanning, Dependabot alerts, CodeQL, and Secret scanning).
View information about pull requests and work items in the
Use GitHub metrics in to understand key metrics and gain insight into services, incident response, and more.
Create that track progress and drive alignment on projects involving your repositories.
If you connect Cortex via a , it must be configured with a token containing the minimum permissions listed below.
Note: The is preconfigured with these permissions.
Permission
Requirement
Purpose(s) in Cortex
Actions
Read & write
Read workflow run information for Git-based CQL rules
Artifact information for actions
Administration
Read & write
Create repositories
Checks
Read & write
Used by Cortex's GitHub app linter on pull requests
Code scanning alerts
Read-only
Get vulnerability information for Git-based CQL rules
Commit statuses
Read & write
Read commits for an entity's Git metadata
Read commits for Git-based CQL rules
Show pending status messages on the OpenAPI incompatibility check
Contents
Read & write
Read cortex.yaml
, cortex-properties.yaml
, and package/OpenAPI files
Read Git rules
Create file contents
Custom properties
Read & write
Dependabot alerts
Read-only
Read vulnerability information for Git CQL rules (only relevant if using Dependabot)
Deployments
Read & write
Issues
Read & write
Read associated issues with repositories for populating entity Git integration and for Git CQL rules
Metadata
Read-only
Read associated data with repositories for populating entity Git integration and for Git CQL rules
Pull requests
Read & write
Read pull request data for Git CQL rules and developer homepage "My PRs" tab
Comment if there are breaking OpenAPI changes on a PR
Search code for non-public files
Read-only
Secret scanning alerts
Read-only
Read vulnerability information for Secret scanning
Single file
Read & write
(Path to cortex.yaml
)
Read cortex.yaml
files
Create cortex.yaml
files
Workflows
Read & write
Write in GitHub actions files
Administration
Read & write
Create repositories
Members
Read & write
Read membership information for ownership and team composition
Secrets
Read & write
Optionally write repo secrets after creating new repo
There are multiple options for connecting Cortex to your GitHub instance:
Through Cortex's official GitHub app
Through a custom GitHub app
By using Cortex's official GitHub app or a custom GitHub app, users can tag entities with Git details and enable GitOps-style configuration of data in Cortex.
Using a personal access token
Using Cortex Axon Relay, a relay broker that allows you to securely connect your on-premises GitHub data.
See the tabs below for instructions on each of the GitHub integration options.
To set up the app:
In Cortex, click your avatar in the lower left corner, then click Settings.
Under "Integrations," click GitHub.
Follow the prompts, then click Install & Authorize.
Cortex's GitHub app is preconfigured with:
The app comes with a built-in linter, which validates a given cortex.yaml
file and checks Cortex-specific items. However, the linter DOES NOT validate data correctness. For example, the linter will confirm that the format of a group block is correct, but will not check that the group exists.
Note: The linter in Cortex's official GitHub app only validates the format of data, not content.
The GitHub integration has multi-account support. You can add a configuration for each additional organization, instance, or account by repeating the process above.
Each configuration requires an alias, which Cortex uses to correlate the designated organization, instance, or account with registrations for various entities. Registrations can also use a default configuration without a listed alias. You can edit aliases and default configurations from the GitHub page in your Cortex settings. Select the edit icon next to a given configuration and toggle Set as default on. If you only have one configuration, it will automatically be set as the default.
Repository
You can define a GitHub repository for a given entity by adding the x-cortex-git
block to the entity's descriptor. When you define a repository, Cortex checks for Security Advisory vulnerabilities from the GraphQL API and Advanced Security vulnerabilities from the Rest API.
repository
GitHub repository in the form /
✓
basepath
Subdirectory for the entity if it is in a monorepo. Note that setting a basepath
filters the vulnerabilities that appear in Cortex; Advanced Security vulnerabilities will not appear.
alias
Alias for the configuration in Cortex (only needed if you have opted into multi-account support)
Only one repository can be defined for in a given entity's YAML in the x-cortex-git
block. Users looking to list additional repositories without the full functionality of GitOps can define the repos as custom data.
Ownership
You can define the following block in your Cortex entity descriptor to add your GitHub teams.
type
Ownership type; must be defined as group
for GitHub teams
✓
name
GitHub team name in the form /
Team names are generally converted to lowercase with -
separators (Team Name
would be cortex/team-name
), but you can verify your exact name from the GitHub permalink
✓
provider
Name of integration (in this case, GITHUB
)
✓
description
Description for the GitHub team
Multiple GitHub organizations are not supported for ownership, and Cortex will use the default configuration when fetching teams.
Cortex maps users' email addresses to discovered GitHub accounts, so you never need to define email ownership in an entity descriptor. Users must be members of GitHub teams to be pulled in to Cortex.
Vulnerabilities appear in the Vulnerabilities block under Code & security on an entity page overview.
Click Code & security in an entity's sidebar to view the full list of vulnerabilities for an entity. Cortex checks for:
Security Advisory vulnerabilities from the GraphQL API
Cortex pulls data from code scanning, Dependabot alerts, CodeQL, and Secret scanning.
Dependency reviews are not supported.
GitHub Advanced Security vulnerabilities are not surfaced for monorepos.
Events
Recent commits appear at the top of an entity's overview page.
You can also click Events in the entity's sidebar to see all commits and releases associated with that entity. Each is hyperlinked to the commit or release page in GitHub and includes a timestamp.
Repository
You can access more detailed information pulled from GitHub in the Repository page in the sidebar. At the top of the page, you'll find the repo(s) associated with that entity and the most-used language in files for that entity. In the Top contributors block, you'll find the three users who have contributed the most code and the number of their contributions.
In the Commits section, you'll find the 10 most recent commits and metadata about each. Below Commits is the Recent releases section, which includes the 5 most recent releases.
Issue tracking
Packages
CI/CD - GitHub workflows
Pull requests and issues from GitHub are refreshed every 2 minutes.
Average PR open to close time
Avg time to first review
Avg time to approval
PRs opened
Weekly PRs merged
Avg PRs reviewed/week
Avg commits per PR
Ave lines of code changed per PR
With the GitHub integration, you can create Scorecard rules and write CQL queries based on GitHub data.
Ownership CQL
External repositories
By default, each GitHub rule is evaluated on the repository defined in a given entity descriptor. If the base path parameter has been set, CQL rules will automatically scope to the base path subdirectory.
To evaluate the rule for a service for an external repository, pass the repo identifier in the git(repoIdentifier: Text)
command (e.g. git("github:org/repositoryName")
).
This can be combined with other CQL rules. For example, a rule based on a dynamic external repository with custom data would be git("github:" + custom("my-custom-repo")).fileExists("README.md")
.
Cortex conducts a background sync of GitHub identities every day at 10 a.m. UTC. Pull requests and issues are refreshed every 2 minutes.
I'm getting this error: "{"message":"Not Found", "documentation_url":"https://docs.github.com/rest/repos#get-a-repository"}"
.
If you've set up multiple GitHub accounts/organizations, Cortex will not be able to identify the correct one unless the alias
variable is defined.
What if I have multiple email addresses set in my GitHub account?
Cortex will only detect the primary email address associated with your GitHub account if it is public.
If Cortex is not correctly pulling in user emails, ensure the given user(s) have allowed their email address to be public. Make sure the "Keep my email address private" setting is unchecked in the user's personal GitHub settings.
My ownership isn't being automatically mapped through GitHub.
If the email address associated with your Cortex account is not the same as your GitHub email address, you need to add your Cortex email address to the Public email dropdown in GitHub settings.
Github OAuth, which you can configure in Cortex user settings, allows you to link your GitHub username with your Cortex account, even if you don't have a public email set up on GitHub.
The following options are available to get assistance from the Cortex Customer Engineering team:
Chat: Available in the Resource Center
Slack: Users with a connected Slack channel will have a workflow added to their account. From here, you can either @CortexTechnicalSupport or add a :ticket:
reaction to a question in Slack, and the team will respond directly.
Don’t have a Slack channel? Talk with your Customer Success Manager.
Used in
Used in
Create new issues based on
Used in
Write permission used in
If your GitHub setup involves multiple organizations, you can add multiple GitHub apps, use a that has access to all orgs, or create multiple configurations with corresponding aliases.
Reach out to support at to receive details about our static IP. If you're unable to directly allowlist our static IP, you can route requests through a secondary proxy in your network that has this IP allowlisted and have that proxy route traffic to your GitHub instance.
is the easiest way to connect your GitHub instance. It is preconfigured with the needed to use this integration. Note that it is not available for Cortex Server.
In Cortex, navigate to the :
On the GitHub settings page, next to cortex default
, click Install.
Permissions for , , and the .
Webhooks to enable .
Support for using as an ownership provider.
Make sure you have configured the permissions listed above under .
. When you're creating the app, make sure to follow these steps:
Set the repository and organization outlined in the configuration modal.
In Cortex, navigate to the :
Client ID: Enter the unique assigned to your app during registration.
Private key: Enter the to authenticate with your GitHub app.
Before getting started, make sure your has, at minimum, the repo
and read:org
permissions.
In Cortex, navigate to the :
See for instructions.
Configure the integration for multiple GitHub accounts
Cortex supports mapping multiple identities for a single user if you have multiple configurations of GitHub. See the for more information.
See the for instructions on importing entities.
You can confirm users' GitHub accounts are connected from .
The GitHub integration will populate the Repo and Language detail blocks on an . If a GitHub team has been for an entity, it will also appear in the Owners block.
vulnerabilities
You can query for vulnerabilities with CQL and create Scorecard rules based on security metrics. See below.
From the Issue tracking page in the entity's sidebar, you can find a list of open . Each issue will show the number, title, assignees, and date created.
From the CI/CD > GitHub workflows page in the entity's sidebar, you can find a history of runs for the past week. Each run is tagged with its status: IN_PROGRESS
, COMPLETED
, SUCCESS
, CANCELLED
, FAILURE
, PAUSED
.
The GitHub workflows page displays data about workflows in GitHub, not Workflows initiated via .
When a with a team entity, Cortex will pull GitHub users in to the Members tab. When available, Cortex will pull in the profile picture and email address for each user.
The GitHub integration enables Cortex to pull information about pull requests and issues into the . You can find your open pull requests, any pull requests assigned to you for review, and any issues assigned to you.
The uses pull request data from GitHub to generate metrics:
You can read more about how Eng Intelligence tracks metrics for teams and users in the .
To add deployments for your Github related entity, you can send a deployment event to the .
See more examples in the in Cortex.
Email: , or open a support ticket in the in app Resource Center
Packages are automatically scraped from your Git repos or they can be submitted via the . The package file must be in the root of your repository — or, if you're using basepath
, in the root of the subdirectory — to be scraped by Cortex. You can query an entity's packages in using packages()
.
To view packages, click Packages in the entity's sidebar.
The following package types are automatically scraped from repositories:
JavaScript / Node.js: package.json
, package-lock.json
, yarn.lock
, pnpm-lock.yaml
Python: requirements.txt
, pipfile.lock
.NET (C#): packages.lock.json
Java: pom.xml
Go: go.sum
All other files of these types can be added via the .