GitHub
Overview
GitHub 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 entity's details page, 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 GitHub Advanced Security (Code scanning, Dependabot alerts, CodeQL, and Secret scanning)
View information about pull requests and work items in the engineering homepage
Use GitHub metrics in Eng Intelligence to understand key metrics and gain insight into services, incident response, and more
Create Scorecards that track progress and drive alignment on projects involving your repositories
How to configure GitHub with Cortex
Prerequisites
If you connect Cortex via a custom GitHub app, it must be configured with a fine-grained personal access token containing the minimum permissions listed below.
Note: The Cortex GitHub app is preconfigured with these permissions.
Repository 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 filesRead Git rules
Create file contents
Dependabot alerts
Read-only
Read vulnerability information for Git CQL rules (only relevant if using Dependabot)
Issues
Read & write
Read associated issues with repositories for populating entity Git integration and for Git CQL rules
Create new issues based on Initiatives
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
Secret scanning alerts
Read-only
Read vulnerability information for Secret scanning
Single file
Read & write
(Path to cortex.yaml
)
Read
cortex.yaml
filesCreate
cortex.yaml
files
Workflows
Read & write
Write in GitHub actions files
Organization-level permissions
Administration
Read & write
Create repositories
Members
Read & write
Read membership information for ownership and team composition
Write permission used in Workflows
Secrets
Read & write
Optionally write repo secrets after creating new repo
Choose a configuration option
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.
If your GitHub setup involves multiple organizations, you can add multiple GitHub apps, use a personal access token that has access to all orgs, or create multiple configurations with corresponding aliases.
See the tabs below for instructions on each of the GitHub integration options.
Configure GitHub with the Cortex GitHub app
Cortex's official GitHub app is the easiest way to connect your GitHub instance. It is preconfigured with the permissions needed to use this integration. Note that it is not available for Cortex Server.
To set up the app:
In Cortex, navigate to the GitHub settings page:
In Cortex, click your avatar in the lower left corner, then click Settings.
Under "Integrations," click GitHub.
On the GitHub settings page, next to
cortex default
, click Install.Follow the prompts, then click Install & Authorize.
Cortex's GitHub app is preconfigured with:
Permissions for catalogs, Scorecards, and the Scaffolder.
Webhooks to enable GitOps.
Support for using GitHub teams as an ownership provider.
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.
Configure the integration for multiple GitHub accounts
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.
Cortex supports mapping multiple identities for a single user if you have multiple configurations of GitHub. See the Identity mapping documentation for more information.
Registration
See the Create services documentation for instructions on importing entities.
Entity descriptor
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.
x-cortex-git:
github:
repository: cortex/docs
basepath: myService
alias: myApp
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.
x-cortex-custom-metadata:
second-git-repo:
- `/`
third-git-repo:
- `/`
Ownership
You can define the following block in your Cortex entity descriptor to add your GitHub teams.
x-cortex-owners:
- type: group
name: cortex/engineering
provider: GITHUB
description: This is a description for this GitHub team that owns this entity.
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.
Identity mappings
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.
You can confirm users' GitHub accounts are connected from GitHub identity mappings in settings.
Using the GitHub integration
View GitHub data on entity pages in Cortex
The GitHub integration will populate the Repo and Language detail blocks on an entity's details page. If a GitHub team has been defined as the owner for an entity, it will also appear in the Owners block.
Code & security
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
GitHub Advanced Security vulnerabilities
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.
You can query for vulnerabilities with CQL and create Scorecard rules based on security metrics. See Scorecards and CQL below.
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
From the Issue tracking page in the entity's sidebar, you can find a list of open GitHub issues. Each issue will show the number, title, assignees, and date created.
Packages
Packages are automatically scraped from your Git repos or they can be submitted via the packages API. 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 CQL explorer 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 packages API.
CI/CD - GitHub workflows
From the CI/CD > GitHub workflows page in the entity's sidebar, you can find a history of GitHub workflow 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 Cortex's Workflows tool.
Team entity pages
When a GitHub team is registered 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.
Engineering homepage
The GitHub integration enables Cortex to pull information about pull requests and issues into the homepage. You can find your open pull requests, any pull requests assigned to you for review, and any issues assigned to you.
Pull requests and issues from GitHub are refreshed every 2 minutes.
Eng Intelligence
The Eng Intelligence tool uses pull request data from GitHub to generate metrics:
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
You can read more about how Eng Intelligence tracks metrics for teams and users in the Eng Intelligence documentation.
To add deployments for your Github related entity, you can send a deployment event to the Cortex API.
Scorecards and CQL
With the GitHub integration, you can create Scorecard rules and write CQL queries based on GitHub data.
See more examples in the CQL Explorer in Cortex.
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")
.
Background sync
Cortex conducts a background sync of GitHub identities every day at 10 a.m. UTC. Pull requests and issues are refreshed every 2 minutes.
FAQs and troubleshooting
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.
Still need help?
The following options are available to get assistance from the Cortex Customer Engineering team:
Email: [email protected], or open a support ticket in the in app Resource Center
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.
Last updated
Was this helpful?