LogoLogo
Login to CortexBook a DemoCortex Academycortex.io
  • Cortex Docs
  • Cortex Quick Start
  • Ingesting data into Cortex
    • Managing Entities
      • Adding entities
        • Add services
        • Add domains
        • Add teams
        • Add custom entity types
        • Defining dependencies
      • Entity details page
      • Defining ownership
      • Defining relationship types
      • Grouping entities
      • Adding external documentation
      • Adding Deploy data
      • Adding custom data
      • Viewing discovered entities
      • Archiving entities
      • Relationship graph
      • Using On-call Assistant for incidents
      • Managing Terraform infra in Cortex
    • Managing Catalogs
    • Integrations
      • Internally hosted integrations
      • ArgoCD
      • AWS
      • Azure DevOps
      • Azure Resources
      • BambooHR
      • Bitbucket
      • BugSnag
      • Buildkite
      • Checkmarx
      • CircleCI
      • ClickUp
      • Codecov
      • Coralogix
      • Custom webhook integrations
      • Datadog
      • Dynatrace
      • Entra ID (Azure AD)
      • FireHydrant
      • GitHub
      • GitLab
      • Google
      • Grafana
      • incident.io
      • Instana
      • Jenkins
      • Jira
      • Kubernetes
      • LaunchDarkly
      • Lightstep
      • Mend
      • Microsoft Teams
      • New Relic
      • Okta
      • Opsgenie
      • PagerDuty
      • Prometheus
      • Rollbar
      • Rootly
      • Sentry
      • ServiceNow
      • Slack
      • Snyk
      • SonarQube
      • Splunk Observability Cloud (SignalFx)
      • Splunk On-Call (VictorOps)
      • Sumo Logic
      • Veracode
      • Wiz
      • Workday
      • xMatters
  • Scorecards
    • Initiatives and Action items
      • Creating issues based on Initiatives
    • Scorecard rule exemptions
    • Scorecard rule filters
    • Scorecard examples
    • Scorecards as code
  • Reports
    • Executive report
    • All Scorecards report
    • Bird's eye report
    • Progress report
    • Report card
  • Eng Intelligence
    • Custom Metrics
    • Jira Metrics
    • Metrics Explorer (Beta)
  • Cortex Query Language (CQL)
    • Using CQL reports
    • Using JQ in Cortex
  • Workflows
    • Creating a Workflow
      • Workflows as code
    • Blocks
    • Running a Workflow
    • Registering a Scaffolder template
      • Scaffolder advanced usage
    • Using a Workflow to sync in ArgoCD
    • Kicking off a Jenkins pipeline in a Workflow
    • Calling internal service endpoints in a Workflow
  • Plugins
    • Creating a plugin
      • Creating a plugin proxy
    • Migrating Backstage plugins to Cortex
  • Engineering homepage
  • Workspace Settings
    • Using GitOps for Cortex
      • GitOps logs
    • Managing users
      • Roles and permissions
        • Custom roles
        • Team ownership entity editing
      • Configuring SSO
        • Microsoft Entra ID
        • Google
        • Other OIDC providers
        • Okta
          • Okta SCIM
      • Configuring identity mappings
      • Onboarding management
    • API keys, secrets, and tokens
      • Secrets
      • Personal tokens
    • Audit logs
    • Entity settings
      • Data verification
      • Auto archiving entities
    • IP allowlist
    • Notifications
      • Notification logs
    • Customizing your workspace
    • Using search in Cortex
  • Cortex API
    • REST API operations
      • API Keys
      • Audit Logs
      • Catalog Entities
      • Custom Data
        • Custom Data (Advanced)
      • Custom Events
      • Custom Metrics
      • Dependencies
      • Deploys
      • Discovery Audit
      • Docs
      • Eng Intel: User Labels
      • Entity Relationship Types (Beta)
      • Entity Relationships (Beta)
      • Entity Types
      • GitOps Logs
      • Groups
      • Initiatives
      • Integrations APIs
        • Azure Active Directory (Entra ID) API
        • Azure Resources API
        • AWS API
        • Azure DevOps API
        • CircleCI API
        • Coralogix API
        • Datadog API
        • GitHub API
        • GitLab API
        • incident.io API
        • LaunchDarkly API
        • New Relic API
        • PagerDuty API
        • Prometheus API
        • SonarQube API
      • IP Allowlist
      • Notification Logs
      • On call
      • Packages
      • Plugins
      • Queries
      • SCIM
      • Scorecards
      • Secrets
      • Team Hierarchies
      • Teams
      • Workflows
Powered by GitBook
On this page
  • Overview
  • How to configure GitHub with Cortex
  • Prerequisites
  • Choose a configuration option
  • Registration
  • Entity descriptor
  • Identity mappings
  • Expected results
  • Entity pages
  • Team entity pages
  • Engineering homepage
  • Eng Intelligence
  • Scorecards and CQL
  • Background sync
  • FAQs and troubleshooting
  • Still need help?​

Was this helpful?

Export as PDF
  1. Ingesting data into Cortex
  2. Integrations

GitHub

Last updated 5 days ago

Was this helpful?

Overview

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.

How to configure GitHub with Cortex

Prerequisites

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.

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 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

Organization-level permissions

Permission
Requirement
Purpose in Cortex

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

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.

See the tabs below for instructions on each of the GitHub integration options.

If you're using a self-hosted instance of GitHub, you'll need to verify that your Cortex instance is able to reach the GitHub instance. We route our requests through a static IP address.

Configure GitHub with the Cortex GitHub app

To set up the app:

    1. In Cortex, click your avatar in the lower left corner, then click Settings.

    2. Under "Integrations," click GitHub.

  1. 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.

Configure GitHub with a custom app

If you're using Cortex Server, or if you don't want to use the official Cortex app, you can connect a custom GitHub app.

Step 1: Register the custom app

    • Disable "Expire user authorization tokens." (Cortex does not support this OAuth workflow yet.)

    • Select "Request user authorization (OAuth) during installation."

    • Callback URL: https://app.getcortexapp.com/github/redirect/{alias}

    • Webhook URL: https://api.getcortexapp.com/api/internal/v1/github/webhook

    • Add a webhook secret identical to the secret in Cortex settings.

    • Check Push and Check suite under Subscribe to events.

  1. After the app has been created, generate a client secret and private key.

Step 2: Configure the custom app in Cortex

    1. In Cortex, click your avatar in the lower left corner, then click Settings.

    2. Under "Integrations," click GitHub.

  1. Click Add configuration, then for the type, select GitHub app.

  2. Fill in the form:

    • Alias: Enter the name Cortex will associate with a given configuration.

    • Application ID: Enter the ID for your custom GitHub ap.

    • Client secret: Enter the unique client secret assigned to your app during registration.

    • Public link: Enter the public URL of your GitHub app.

    • API endpoint (for GitHub enterprise): Enter the endpoint root URL for self-managed GitHub setups.

  3. Click Save.

  4. On the GitHub Settings page in Cortex, next to your custom app configuration's name, click Install.

Configure GitHub with a personal access token

Prerequisites

Note: Beyond the minimum permissions indicated above, many scenarios will require that the user who generated the personal access token have organization ownership permissions within GitHub.

Configuration

    1. In Cortex, click your avatar in the lower left corner, then click Settings.

    2. Under "Integrations," click GitHub.

  1. Click Add configuration.

  2. In the upper right corner of the modal, click the dropdown and select Personal access token.

  3. Fill in the form:

    • Alias: Enter a name that Cortex will associate with a given configuration.

    • Token: Enter the Personal access token generated in GitHub.

    • API endpoint (for GitHub enterprise): Enter the endpoint root URL for self-managed GitHub setups.

  4. Click Save.

Configure GitHub with Cortex Axon Relay

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.

To write rules related to Dependabot alerts, you must verify the necessary permissions are set for repositories you'd like to see vulnerabilities reported on.

To verify, navigate to a repository on GitHub and click "Settings" → "Code security and analysis". Make sure you are a member of a team under "Access to alerts.

Registration

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
Field
Description
Required

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.
Field
Description
Required

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.

Expected results

Entity pages

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

    • 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

Team entity pages

Engineering homepage

Pull requests and issues from GitHub are refreshed every 2 minutes.

Eng Intelligence

  • 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

Scorecards and CQL

With the GitHub integration, you can create Scorecard rules and write CQL queries based on GitHub data.

Approvals required to merge

Number of approvals required to merge a pull/merge request into a repository. Defaults to 0 if no approvals are defined.

Definition: git.numOfRequiredApprovals()

Examples

For a security or development maturity Scorecard, you can write a rule to make sure at least one approval is required to merge a pull/merge request:

git.numOfRequiredApprovals() > 0

By having a rigorous PR process in place for a repo, you can make sure changes aren't made that create vulnerabilities. This kind of rule could also be used in a best practices or project standards Scorecard.

You can also use a similar expression in the Query Builder to find entities lacking approval:

git.numOfRequiredApprovals() < 1
Git repository set

Check if an entity has a registered Git repository.

Definition: git (==/!=) null: Boolean

Example

In a Scorecard, you can write a rule that detects whether an entity has a Git repository set:

git != null
Pipeline build success rate

The percentage of build pipelines that complete successfully. This is calculated against builds on the default branch, for commits in the last 30 days. The calculation is # successful builds / (# successful + # failed).

Definition: git.percentBuildSuccess(): Number

Example

In a Scorecard, you can write a rule that requires at least 90% of build runs to be successful:

git.percentBuildSuccess() > 0.9
Branches

List all live branches with some basic metadata.

  • Head

  • Is protected

  • Name

Definition: git.branches()

Example

For a best practices Scorecard, you can make sure that branches associated with an entity match a standard naming convention:

git.branches().all((branch) => branch.name.matches("(main|master|feat-.*|bug-.*|task-.*)"))
Branch protection details

Find details for specified branch, or default branch if none is specified.

  • Branch name

  • Code owner reviews required

  • Dismiss stale reviews

  • Required status checks

  • Restrictions apply to admin

  • Review required

Definition: git.branchProtection()

Examples

For a security Scorecard, you can write a rule to make sure the default branch is protected:

git.branchProtection() != null

Because vulnerabilities in the default branch are critical, this rule should be in one of the first couple levels.

You can also use the Query Builder to find entities with unprotected default branches:

git.branchProtection() = null
Commits

Get the latest commits (to a maximum of 100) for a defined lookback period (defaulting to 7 days).

  • Date

  • Message

  • SHA

  • URL

  • Username

These results can be filtered based on branch name, using the default branch if no other branch is provided.

Definition: git.commits()

Example

You can use the git.commits() expression in a security Scorecard to make sure entities have fewer than three commits to a "security-fixes" branch in the last week:

git.commits(branch="security-fixes", lookback=duration("P7D")).length < 3

Entities passing this rule will include those that haven't needed three or more security fixes. This can indicate that there aren't vulnerabilities in a given entity's code, but could also suggest that fixes aren't being implemented. Using this rule in conjunction with one focused on vulnerabilities could provide the extra context needed to gain a better understanding of what's happening.

Default branch

Default branch for the repository, or main when null.

Definition: git.defaultBranch()

Example

If default branches should always be named "main," you can write a rule to make sure entities follow this practice:

git.defaultBranch().matches("main")
File contents

Load the contents of a file from the entity's associated repository.

The contents can be validated by using string comparison operations or parsed by the built-in jq function. The jq function will automatically coerce file contents of JSON or YAML formats.

Definition: git.fileContents()

Example

For a Scorecard focused on development maturity, you could use the git.fileContents() rule to enforce that a CI pipeline exists, and that there is a testing step defined in the pipeline.

git.fileContents("circleci/config.yml").matches(".*npm test.*")

A best practices Scorecard, meanwhile, could use this expression for a number of rules:

  • To make sure node engine version in specified in the package.json file:

    jq(git.fileContents("package.json"), ".engines.node") != null
  • To make sure TypeScript projects have a tsconfig.json file checked in:

    jq(git.fileContents("package.json"), ".devDependencies | with_entries(select(.key == \"typescript\")) | length") == 0 or git.fileExists("tsconfig.json")
  • To make sure projects using yarn do not allow NPM:

    jq(git.fileContents("package.json"), ".engines.yarn") == null or jq(git.fileContents("package.json"), ".engine.npm") = "please-use-yarn"
  • And to ensure the yarn version being used is not deprecated:

    jq(git.fileContents("package.json"), ".engines.yarn") == null or !(semver("1.2.0") ~= semverRange(jq(git.fileContents("package.json"), ".engines.yarn")))
File exists

Check if file exists from within the entity's associated repository.

Definition: git.fileExists()

Examples

For a Scorecard focused on best practices, you can make sure that repositories contain a README.md file:

git.fileExists("README.md")

This rule would make sense in the first level because it's so essential.

A higher-level rule in a best practices Scorecard might confirm that developers are checking in lockfiles to ensure consistency in package installs:

git.fileExists("yarn.lock") OR git.fileExists("package-lock.json")

And/or a rule that makes sure there are unit tests enabled:

git.fileExists("*Test.java")

Finally, you could write a rule to make sure projects have a standard linter:

git.fileExists(".prettierrc.json") OR git.fileExists(".eslintrc.js")
Number of Git vulnerabilities

Check the number of vulnerabilities for an entity's associated repository.

You can filter by severity (by default searches by all severities) or source (by default only searches GitHub security advisories).

When using the GitHub Advanced Security source, severities displayed in the UI may not match severities returned by the API.

Definition: git.numOfVulnerabilities()

Examples

A security-focused Scorecard will likely include a rule making sure there are no Git vulnerabilities:

git.numOfVulnerabilities() == 0

You can use Scorecard levels to stratify vulnerabilities by risk. An initial level might make sure there are no critical vulnerabilities:

git.numOfVulnerabilities(severity=["CRITICAL"]) == 0

While a higher level might make sure there are no vulnerability warnings:

git.numOfVulnerabilities(severity=["WARNING"]) == 0
List of Git vulnerabilities

Lists the vulnerabilities for an entity's associated repository. You can filter by severity (by default searches by all severities) or source (by default only searches GitHub security advisories). Note when using the GitHub Advanced Security source, severities displayed in the UI may not match severities returned by the API.

Definition: git.vulnerabilities()

Examples

You could write a Scorecard rule that verifies an entity has fewer than 5 Git vulnerabilities:

git.vulnerabilities().length < 5

You could write a rule that verifies the entity has no vulnerabilities with "High" or "Critical" severity sourced from GitHub Advanced Security:

git.vulnerabilities(severity=["CRITICAL", "HIGH"], source=["GITHUB_ADVANCED_SECURITY"]).length < 1
Has Cortex YAML

Check if a repository has a valid cortex.yaml file checked in at the root directory (when GitOps is enabled).

Definition: git.hasCortexYaml()

Example

If you're using a Scorecard to track a migration from Cortex UI to GitOps, you can use this rule to make sure entities are set up for GitOps management of entity descriptors:

git.hasCortexYaml() == true
Last commit details

Provides last commit details.

  • Date

  • Message

  • SHA

  • URL

  • Username

Definition: git.lastCommit()

Examples

One of the first rules you might write for a Scorecard focused on development maturity or security is one validating that the last commit was within the last month:

git.lastCommit().freshness < duration("P1M")

As counterintuitive as it may seem, services that are committed too infrequently are actually at more risk. People who are familiar with the service may leave a team, institutional knowledge accumulates, and from a technical standpoint, the service may be running outdated versions of your platform tooling.

Depending on best practices at your organization, you may want to confirm entities are updated within a week:

git.lastCommit().freshness < duration("P7D")

Confirming whether a service was updated within the last week can help team members catch outdated code sooner. Plus, if there is a security issue, you can quickly determine which services have or have not been updated to patch the vulnerability.

Pull requests

Lists pull requests opened during a defined lookback period.

  • Approval date

  • Author

  • Date closed

  • Date opened

  • First review date

  • Last updated

  • Number of commits

  • Number of lines added

  • Number of lines deleted

  • Organization

  • Repository

  • Source

  • Status

  • URL

Definition: git.pullRequests()

Example

You can use the git.pullRequests() query to find entities that have a small number of pull requests opened in the last two weeks:

git.pullRequests(lookback=duration("P14D")).length < 3

This can highlight entities that haven't been updated recently, which may be especially useful when entities have to be updated to address a vulnerability.

Reviews

List reviews left during a defined lookback period.

  • Organization

  • Repository

  • Review date

  • Reviewer

Definition: git.reviews()

Examples

A development maturity Scorecard might use the git.reviews() expression to make sure that there is a rigorous review process in place before changes are implemented:

git.reviews(lookback=duration("P7D")).length > 25

This rule makes sure that there are more than 25 reviews left in the last week.

Workflow runs

Get workflow runs meeting given filter criteria, including conclusions, statuses, and a lookback period.

  • Conclusion

  • Name

  • Run started at

  • Run time

  • Run updated at

  • Status

Conclusions: FAILURE, SUCCESS, TIMED_OUT

Statuses: QUEUED, IN_PROGRESS, COMPLETED

The lookback period specifies a duration for which returned runs should be created within, defaulting to a period of 3 days.

  • The runTime of the WorkflowRun object represents the difference between runStartedAt and runUpdatedAt times in seconds.

Definition: git.workflowRuns()

Example

To make sure an entity has had a successful workflow run within the last two weeks, you can write a rule like:

git.workflowRuns(conclusions=["SUCCESS"], statuses=["COMPLETED"], lookback=duration("P14D")).length > 0

This rule is checking for GitHub workflow runs with a SUCCESS conclusion and COMPLETED status during a 14-day lookback window.

Ownership CQL

All ownership details

A special built-in type that supports a null check or a count check, used to enforce ownership of entities.

Definition: ownership: Ownership | Null

Example

An initial level in a security Scorecard might include a rule to ensure an entity has at least one team as an owner:

ownership.teams().length > 0
All owner details

List of owners, including team members and individual users, for each entity

Definition: ownership.allOwners()

Example

The Scorecard might include a rule to ensure that entity owners all have an email set:

ownership.allOwners().all((member) => member.email != null)
Team details

List of teams for each entity

Definition: ownership.teams(): List<Team>

Example

The Scorecard might include a rule to ensure that an entity owners all have a description and are not archived:

ownership.teams().all(team => team.description != null and team.isArchived == false)

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.

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.

Still need help?

Email: , or open a support ticket in the in app Resource Center

help@cortex.io
GitHub settings page
GitOps
GitHub teams
Register the app
GitHub settings page
client ID
private key
personal access token
GitHub settings page
Internally hosted integrations
​
Identity mapping documentation
GitHub identity mappings in settings
GitHub Advanced Security
GitHub issues
GitHub workflow
Cortex's Workflows tool
homepage
Eng Intelligence tool
Eng Intelligence documentation
Cortex API
CQL Explorer
​
help@cortex.io
GitHub
GitHub Advanced Security
Eng Intelligence
fine-grained personal access
entity's details page
engineering homepage
Scorecards
custom GitHub app
Cortex GitHub app
personal access token
Cortex's official GitHub app
permissions
Prerequisites
permissions
entity's details page
defined as the owner
Scorecards and CQL
GitHub team is registered
Workflows
Workflows
Initiatives
Workflows
Workflows
catalogs
Scorecards
Scaffolder
Create services documentation

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 .

packages API
CQL explorer
packages API