Skip to main content

GitHub Apps Code Repository Integrations

Notice

It is possible to add the Checkmarx One external IP addresses to the customer Firewall allowlist - For more information see Managing Checkmarx One Traffic and AWS S3 Access

Additionally, if the code repository is not internet accessible, it is possible to configure the code repository IP address instead of its hostname during the initial integration with the code repository - as it is not resolved via DNS.

Overview

Checkmarx supports code repository integrations using GitHub Apps. We offer a "Cloud-Hosted" flow that provides a pre-configured Checkmarx GitHub App. Alternatively, you can use our "Self-Hosted" flow, which enables you to create and configure your own GitHub App (or use an existing one) that conforms to the required settings for Checkmarx integration.

Notice

As for all code repository integrations, single tenant accounts do not have the option to use the cloud hosted flow.

This guide walks through the setup flow, including creating the integration configuration, setting up and configuring a GitHub App when required, installing it in your GitHub organization, and importing specific repositories.

Notice

This integration supports both public and private git based repos.

Once the integration is configured, a separate Checkmarx One Project is created for each connected GitHub repo.

Notice

You can select several repos to create multiple integrations in a bulk action.

Why Connect Using a GitHub App?

Using a GitHub App is the recommended way to connect Checkmarx to your repositories because it provides:

  • Precise, Repo-Level Access Control - Admins can choose exactly which repositories Checkmarx can access. The OAuth method depends on a user’s permissions, which may include far more repositories than intended.

  • Stronger Security Through Least Privilege - GitHub Apps request only the specific permissions needed (e.g., read-only code access). OAuth uses broad scopes that often grant full repo access.

  • Organization-Owned and Not Tied to a User - The GitHub App belongs to the organization—not an individual. This means the integration stays active even when team members change roles or leave.

  • Short-Lived Tokens Instead of Long-Lived User Credentials - GitHub Apps use automatically rotated, short-lived tokens, reducing risk exposure. OAuth relies on long-lived user tokens that require manual management.

Prerequisites

  • The source code for your project is hosted on a GitHub repo.

  • You need to be authenticated in GitHub.

    Notice

    Installing the GitHub App requires admin approval. If you aren't authenticated as an org admin, you will need to wait for an admin to approve your request. After the initial installation, non-admins can configure and edit code repository integrations.

  • You have a Checkmarx One account and have credentials to log in to your account.

    Important

    Creating new import configurations or editing existing configurations requires update-tenant-params permission. Importing new Projects using an existing configuration requires create-project permission.

    Our best practice recommendation is to create a dedicated service user for the purpose of creating the integration. This will ensure that scans created via the integration will have a representative name.

Required Permissions in GitHub Apps

Checkmarx requires certain permissions to be assigned to the GitHub App in order to enable Checkmarx to properly interact with your GitHub organization.

The following is a list of the permissions required and why Checkmarx needs these permissions.

  • Commit statuses (read and write) - Update commit status indicators (e.g., pending, success, failure) on commits and pull requests.

  • Pull requests (read and write) - Read and interact with pull requests.

  • Contents (read and write) - Access repository files for code analysis.

  • Issues (read and write) - Create/update FeedbackApp issues, handle GitHub comments, and decorate pull requests.

  • Metadata (read only) - Retrieve basic repository information.

  • Member Organization (read only) (Only for Cloud-Hosted flow) - handle user authentication and organization display.

Project Migration

You can migrate existing manual projects in Checkmarx One to become Code Repository Integration projects using GitHub Apps, using the following procedure:

Notice

This procedure can also be done via REST API, using the Code Repository Conversion API. However, for integrations using our Self Hosted flow, the initial step of creating a code repository instance (by submitting an Instance Name, URL, and authentication credentials) must be done via the UI. And, for integrations using our Cloud Hosted flow, the complete process of importing the organization must be done via the UI.

  1. Go to Integrations Integrations.png > Project Migration.

  2. Select the checkbox for the relevant projects.

  3. Click on Connect to Code Repository.

    The configuration wizard opens in a side-panel.

    Image_562.png

  4. Select Cloud-Hosted or Self-Hosted according to your deployment then select GitHub App and click Next.

  5. Continue with the configuration flow as explained below for Cloud-Hosted or Self-Hosted according to your selection.

GitHub Apps Cloud-Hosted Flow

This flow provides a simple implementation based on a pre-configured GitHub App provided by Checkmarx. This flow is available for Multi Tenant Checkmarx accounts using GitHub Cloud or GitHub Enterprise Cloud accounts.

We offer an alternative Self Hosted procedure flow that involves configuring your own GitHub App. The Self-Hosted flow must be used for:

  • Checkmarx One single tenant accounts

  • Repos hosted on GitHub Server or GitHub Enterprise Server accounts

  • Organizations that prefer to configure their own Apps or use existing Apps

Setting up the Integration and Initiating a Scan

To integrate your GitHub repos with Checkmarx One by means of installing our ready-to-use Checkmarx GitHub App in your organization, perform the following:

Note

Checkmarx GitHub App does not support integration with GitHub user organizations.

Note

If a GitHub organization is renamed or moved, the existing connection becomes invalid. In such cases, the organization must be reimported to restore the integration.

  1. On the Workspace.png > Projects page, click on New > New Project - Code Repository Integration.

    Code_Repo_Integration.png

    The Import From window opens.

  2. Select Cloud-hosted and GitHub App, then click Next.

    GitHub_Select.png

  3. For first-time use, you will be redirected to the GitHub permissions page. Click Authorize.

    Image_076.png

    Enter your authentication code to confirm access, and then click Verify.

    6428295198.png

    You are redirected to the Checkmarx UI and a pop-up install message appears.

  4. In the pop-up message, click Install

    Image_004.png

    You are redirected to the Github App installation page.

  5. Select the organization for which you are creating the integration.

  6. Select the type of access, All repositories or Only select repositories and then click Install.

    Notice

    If you would like to enable this integration to monitor and automatically sync with projects that are added or transferred to your organization, then you must select All repositories. We only recommend selecting Only select repositories if you plan to use this integration for a limited set of repos.

  7. In the pop-up message, click Continue.

  8. Select the GitHub Organization and click Select Organization.

    Note

    Only the organizations in which you installed the GitHub App will appear on the list. You can install the Github App in another organization from this screen by clicking on grant additional organizations in the top right of the screen and repeating the previous steps.

    Image_553.png

  9. Select Repositories inside the GitHub organization and click Select Repositories.

    If the organization contains active repositories, suggested repos will be presented and selected automatically. For additional information see Suggested Repositories.

    Note

    • A separate Checkmarx One Project will be created for each repo that you import.

    • There can’t be more than one Checkmarx One Project per repo. Therefore, once a Project has been created for a repo, that repo is greyed out in the Import dialog.

    Image_555.png

  10. In the Repositories Settings step, you can optionally adjust the settings as follows:

    • If the project has multiple repositories, click All Repositories Settings to adjust the settings for all repositories, or select a specific repository, to adjust the settings for that repository.

      Image_556.png

    • Expand the Permissions Settings and adjust the following settings:

      • Scan Trigger: Push, Pull request - Automatically trigger a scan when a push event or pull request is done in your SCM. (Default: On)

      • Pull Request Decoration - Automatically send the scan results summary to the SCM. (Default: On)

      • SCA Auto Pull Request - Automatically send PRs to your SCM with recommended changes in the manifest file, in order to replace the vulnerable package versions. (Default: Off)

    • Expand the Scanner Settings and enable the toggle for each scanner you want to use (SAST, SCA, IaC Security, Container Security, API Security, OSSF Scorecard, Secret Detection) for your repositories. At least 1 scanner must be selected for each repository.

    • Protected Branches (when a specific repository is selected): Specify the branches to be designated as "Protected Branches".

      Notice

      Specifying a branch as a Protected Branch affects three main areas: scan triggering (for PR and push), policy violation detection, and Feedback App notifications.

      COMING SOON: You can also use a wildcard symbol "*" to designate which branches are protected. The wildcard can be used before the string, after the string, or both. All branches that match the wildcard pattern will be treated as protected branches.

      Examples:

      • * → all branches

      • release* → branches that begin with "release"

      • *release → branches that end with "release"

      • * release * → branches that contain "release" anywhere in the name

      Note

      For additional information about Protected Branches see About Protected Branches

    • Add SSH key (when a specific repository is selected).

    • Assign Tags: Add Tags to the Project. Tags can be added as a simple strings or as key:value pairs.

    • Set Criticality Level: Manually set the project's criticality level.

  11. Click Next.

  12. In the Select Branches screen you can decide whether to enable the "Scan the default Branch upon the creation of the project" feature.

    For each repository, select the protected branches you want to scan during project creation, and then click Create Project.

    Tip

    If you specified a wildcard pattern in the previous step, it will not appear as an option on this list.

    Image_557.png

  13. A Project is created for each repository and a scan is initiated for each project. The new projects are displayed on the Projects page,

    GitHub_scan_initiated.png

    Note

    In order to update the scanners see Imported Project Settings

GitHub Apps Self-Hosted

Notice

This flow involves configuring your own GitHub App according to the required specifications. There is a simpler Cloud-Hosted flow that makes use of a pre-configured Checkmarx One GitHub App. The Cloud-Hosted flow is available only for multi tenant accounts that are connecting to a GitHub Cloud or GitHub Enterprise Cloud organization.

Setting up the Integration and Initiating a Scan

This process involves first connecting to your repo by specifying the repo url and creating a GitHub App to install on a GitHub organization. You then select the repos to import and configure Project settings.

It is possible to configure multiple configurations for connecting to Self-Hosted code repositories, each using a different URL and a different GitHub App. Once the initial configuration is set up, for each subsequent import action you can choose either to use the existing configuration or to create a new one.

Note

Checkmarx does not support GitHub App integrations with GitHub user organizations.

Note

If a GitHub organization is renamed or moved, the existing connection becomes invalid. In such cases, the organization must be reimported to restore the integration.

Step 1: Create the Code Repository Integration

  1. In the Workspace Workspace.png, click on New > New Project - Code Repository Integration.

    Code_Repo_Integration.png

    The Import From window opens.

    Image_558.png

  2. Select Self-Hosted and GitHub Apps.

    Image_560.png

  3. Fill in the following fields:

    • Instance Name - Designate a name for this import configuration.

    • URL - Your GitHub self-managed domain.

      For example: https://github.example.com

    The Set up a new app button is enabled. Continue with the next procedure.

Step 2: Configure the GitHub App

This section walks you through the process of creating a new Checkmarx GitHub App.

Note

If you already have a GitHub App and prefer to use it for your integration, use the alternate procedure described here: Alternate Step 2: Using your own GitHub App.

  1. Click Set up a new app.

    You are redirected to the Register new GitHub App page in GitHub.

    Image_038.png

    Most of the fields are auto-populated by Checkmarx.

  2. In the webhook secret field, enter a password that meets the following criteria:

    • Minimum 16 characters

    • Allowed characters: Letters (a-z, A-Z), numbers (0-9), and symbols (!@#$%^&*-_=+)

    • Not allowed: Spaces, emoji, or special characters (Hebrew, Chinese, etc.)

    Warning

    Checkmarx requires the GitHub webhook secret to follow specific formatting rules. GitHub itself does not enforce these requirements, so it’s possible to create a secret in GitHub that looks valid but will be rejected by Checkmarx. Because of this, you must make sure the secret you generate meets Checkmarx’s criteria before using it.

  3. At the bottom of the page, set the App as allowed for all organizations.

  4. Click Create GitHub App.

    You are brought to your GitHub App details page.

  5. Scroll to the bottom of the page and click Generate a private key.

    The private key is downloaded to your computer.

  6. Leaving this page open, return to the Checkmarx UI and enter the following information:

    • The App id (shown on the top of your GitHub App details page).

    • Click upload private key and select the file that was downloaded in step 5.

    • Fill in the webhook secret field with the secret you created in step 2.

  7. Click Save and continue.

    Your GitHub App is now configured and ready for use in Checkmarx. Continue with the next step.

Alternate Step 2: Using your own GitHub App

If you already have a GitHub App and prefer using it for your integration, carefully follow this procedure:

Warning

A unique Webhook URL is generated for each self hosted Code Repository integration. Therefore, each GitHub App can only be used for one integration.

  1. Click I already have an app.

  2. Copy the webhook url from the information box at the top of the screen and paste it into the webhook url field on your GitHub App's page in GitHub.

  3. Ensure that your GitHub App has the required configurations for use with Checkmarx. This includes:

    • Commit statuses (read and write)

    • Pull requests (read and write)

    • Contents (read and write)

    • Issues (read and write)

    • Metadata (read only)

    • The webhook secret:

      • Must be 16 characters

      • Can use these characters: Letters (a-z, A-Z), numbers (0-9), and symbols (!@#$%^&*-_=+)

      • Cannot have spaces, emoji, or special characters (Hebrew, Chinese, etc.).

    • Set the App as allowed for all organizations.

    • You must enable the following required permissions -

  4. Click Save Changes.

  5. In the Checkmarx UI, ensure data is properly inserted for the following fields:

    • Instance Name - Designate a name for this import configuration.

    • URL - Your GitHub self-managed domain.

      For example: https://github.example.com

    • App ID - the ID of your GitHub App.

    • Private Key - the private key generated in your GitHub App.

    • Webhook Secret - the webhook secret set in your GitHub App.

  6. Click Save and continue.

    Your GitHub App is now configured and ready for use in Checkmarx.

Step 3: Configure the Code Repository Integration.

Now that your GitHub App is configured you can proceed with configuring your code repository integration.

  1. In the pop-up install message that appears, click Install.

    Image_004.png

    You are redirected to the Github App installation page.

  2. Select the GitHub Organization for integration, scroll down, and click Install.

    You are redirected to the Checkmarx UI.

    Note

    To install the GitHub App on another organization, repeat steps 1 and 2.

  3. In the pop-up message, click Continue.

  4. Select the GitHub Organization and click Select Organization.

    Note

    Only the organizations in which you installed the GitHub App will appear on the list. You can install the Github App in another organization from this screen by clicking on Grant additional organizations in the top right of the screen and repeating step 2.

    Image_236.png

  5. Select Repositories inside the GitHub organization and click Select Repositories.

    If the organization contains active repositories, suggested repos will be presented and selected automatically. For additional information see Suggested Repositories.

    Note

    • A separate Checkmarx One Project will be created for each repo that you import.

    • There can’t be more than one Checkmarx One Project per repo. Therefore, once a Project has been created for a repo, that repo is greyed out in the Import dialog.

    GitHub_Select_Repo.png

  6. In the Repositories Settings step, you can optionally adjust the settings as follows:

    • If the project has multiple repositories, click All Repositories Settings to adjust the settings for all repositories, or select a specific repository, to adjust the settings for that repository.

      Image_073.png

    • Expand the Permissions Settings and adjust the following settings:

      • Scan Trigger: Push, Pull request - Automatically trigger a scan when a push event or pull request is done in your SCM. (Default: On)

      • Pull Request Decoration - Automatically send the scan results summary to the SCM. (Default: On)

      • SCA Auto Pull Request - Automatically send PRs to your SCM with recommended changes in the manifest file, in order to replace the vulnerable package versions. (Default: Off)

    • Expand the Scanner Settings and enable the toggle for each scanner you want to use (SAST, SCA, IaC Security, Container Security, API Security, OSSF Scorecard, Secret Detection) for your repositories. At least 1 scanner must be selected for each repository.

    • Protected Branches (when a specific repository is selected): Specify the branches to be designated as "Protected Branches".

      Notice

      Specifying a branch as a Protected Branch affects three main areas: scan triggering (for PR and push), policy violation detection, and Feedback App notifications.

      COMING SOON: You can also use a wildcard symbol "*" to designate which branches are protected. The wildcard can be used before the string, after the string, or both. All branches that match the wildcard pattern will be treated as protected branches.

      Examples:

      • * → all branches

      • release* → branches that begin with "release"

      • *release → branches that end with "release"

      • * release * → branches that contain "release" anywhere in the name

      Note

      For additional information about Protected Branches see About Protected Branches

    • Add SSH key (when a specific repository is selected).

    • Assign Tags: Add Tags to the Project. Tags can be added as a simple strings or as key:value pairs.

    • Set Criticality Level: Manually set the project's criticality level.

  7. Click Next.

  8. In the Select Branches screen you can decide whether to enable the "Scan the default Branch upon the creation of the project" feature.

    For each repository, select the protected branches you want to scan during project creation, and then click Create Project.

    Tip

    If you specified a wildcard pattern in the previous step, it will not appear as an option on this list.

    GitHub_Select_Branches.png

  9. A Project is created for each repository and a scan is initiated for each project. The new projects are displayed on the Projects page,

    GitHub_scan_initiated.png

    Note

    In order to update the scanners see Imported Project Settings

Technical Info About GitHub Webhooks

The webhook listening endpoints and APIs for GitHub self-hosted are similar to those used for GitHub cloud. Detailed info about webhooks for GitHub cloud is available here.GitHub Cloud

Editing Project Settings

To learn about editing Project Settings for an existing code repository integration Project, see Code Repository Project Settings.

In this section: