Code Repository Integrations

TABLE OF CONTENTS
- Overview
- Prerequisites
- Code Repository Integrations page
- Add a new code repository
- Integration with On-premises code repositories
- Delete an existing integration
Overview
This article explains the process of integrating your code repositories with Aqua. Your repositories may be hosted on different Source Code Management tools such as GitHub, Bitbucket, and GitLab. Once you integrate the required code repositories, Aqua will scan them and display the security findings such as vulnerabilities, sensitive data, and misconfigurations in the Code Repositories page.
You can integrate your code repositories using one of the following methods:
- Source Code Management: to integrate with the source code management tools directly by granting their access to Aqua. Through this method, you can also integrate code repositories hosted on on-premises platforms: Azure Server, Bitbucket Server, GitHub Server, and GitLab Server.
- CI Integrations: by adding the Aqua Trivy Premium Scanner to your build pipeline, by following instructions on the UI. Through his method, the source code management tools connected to the pipeline will be scanned and security findings will be detected.
You can connect Aqua to multiple organizations of the same provider.
From the Integrations page, you can also integrate with CI/CD build platforms to detect any security issues in the configurations of the platform. For more information, refer to Integration with Build Platforms.
Prerequisites
- Network access to https://codesec.aquasec.com, for the customers who want to integrate the on-premises source code management tools: Azure Server, Bitbucket Server, GitHub Server, and GitLab Server. For the cloud-based source code management tools, this access is available by default.
- Outbound HTTPS traffic should be allowed from your server to integrate with the on-premises source code management tools. To check Aqua's connectivity from your server, run the following commands from the connector host:
curl https://connect.codesec.aquasec.com/ curl https://scan.codesec.aquasec.com/
- Admin-level privileges to the "Controller" in Jenkins and "Organization" in the other source code management tools, that you want to integrate with Aqua. For example, if you want to integrate a GitHub Organization with Aqua through the Automatic method, you must have "Owner" privilege in the Organization.
Code Repository Integrations page
Once you integrate with a few code repositories through the Source Code Management or CI Integrations methods, all the connections are displayed in the Integrations page as shown below:
You can see the following information in this page:
- Provider: such as GitHub, GitLab, or GitHub Server
- Organization Name: in the provider to which Aqua has been connected
- Status: shows the health of the connection with Aqua: Good or Issue (not good)
You can search or filter the connections using the following options:
- Search: with organization name to find any connection
- Provider: to filter the connections by provider
- Status: to filter the connections by their health: Good, Issue, or All
Add a new code repository
You can add the required code repositories available in the connected source code management tools for scanning them. When the repositories are scanned, Aqua displays scan results in the Code Repositories page.

Source Code Management
To integrate your code repository in the source code management tool using this method:
- On the top right side of the Integrations page, click Connect and select Source Code Management. The Source Code Management selection page will appear.
- Select the required source code management tool. You can click Show More Options to see more tools. The Authentication section appears.
3. In the Authentication section, complete the authentication to the source code management tool as instructed on the UI. This is required to grant Aqua the read/write access to the source code management tool for scanning your code repositories. The authentication process and details required for each source code management tool are different, as explained below.
Source code management tool | Authentication details |
---|---|
Azure |
|
Azure Server | You can connect to your Azure Server (on-premises) account by providing the required permissions on the hosting platform. You should complete authentication on either the Docker or Kubernetes platform by following instructions in the UI. For more information, refer to Integration with On-Premises Code Repositories. |
Bitbucket | Enter the following details:
While creating an app password in Bitbucket:
|
Bitbucket Server | You can connect to your Bitbucket Server (on-premises) account by providing the required permissions on the hosting platform. You should complete authentication on either the Docker or Kubernetes platform by following the instructions in the UI. For more information, refer to Integration with On-Premises Code Repositories. |
GitHub | You should have the GitHub permission as "Organization Owner" to connect Aqua with your repositories. In the Authentication section, click Connect to navigate to GitHub where you can perform the following:
|
GitHub Server | You can connect to your GitHub Server (on-premises) account by providing the required permissions on the hosting platform. You should complete authentication on either Docker or Kubernetes platform by following the instructions in the UI. For more information, refer to Integration with On-Premises Code Repositories. |
GitLab |
While creating a personal access token in GitLab:
|
GitLab Server | You can connect to your GitLab Server (on-premises) account by providing the required permissions on the hosting platform. You should complete authentication on either the Docker or Kubernetes platform by following the instructions in the UI. For more information, refer to Integration with On-Premises Code Repositories. |
Authentication section of the Azure integration is shown below for your reference:

4. In the Repositories section, select the required code repositories that you want Aqua to scan and detect security findings.
5. Click Start Scanning. The repositories will be added, and security findings will be displayed on the Code Repositories page.
You can add any number of repositories to Aqua from an "Organization" in the source code management tool.
Once the selected code repositories are added and scanned, you can see these repositories and their security findings on the Code Repositories page. You can also add more repositories of the connected source code management tool in the Code Repositories page later. For more information, refer to Code Repositories and Checks.
By default, code repositories having activities in the last six months are automatically selected for scanning, while integrating with its source code management tool for the first time. If required, Admins can check these code repositories and remove their selection.
Example: Source Code Management connection with a code repository in GitHub
Watch the video below to see an example on how to connect a code repository in GitHub.
CI Integrations
You can integrate a new code repository manually by adding a code block displayed in the UI to your project in the CI build system. Different code blocks are displayed in the UI, depending on where you want to apply them, as explained below:
- Pull Request: to scan the specific code changes in a pull request. When a new pull request is triggered, Aqua scans the code changes in the pull request automatically and displays scan results in the Code Repositories page. If you select this option, the existing code repository on which the pull request is raised will not be scanned. If you want to scan the full code repository, select the Push option.
- Push: to scan the full code repository. When a new build is triggered, Aqua scans the newly built code repository and displays scan results in the Code Repositories page.
To integrate a code repository in the source code management tool:
- On the top right side of the Integrations page, click Connect and select CI Integrations. The CI Integration page will appear.
- Select the repository hosting platform relevant to your organization, such as GitHub Actions or Bitbucket Pipelines. The Integration Instructions section will appear.

3. Perform the following actions to integrate your code repository with the repository hosting platform. Detailed integration instructions are displayed in the UI for the selected source code management tool.
- In your pipeline settings, add Aqua Key and Aqua Secret as secrets or variables. You can get these details from the CSPM module > Settings > API Keys. These secrets are required to identify the Aqua environment to which the repository will be integrated, and security findings will be generated. The secrets or variables that should be added to your pipeline settings vary depending on the selected repository hosting platform, as explained below:
CI build system | Secrets or variables required |
---|---|
Azure Pipelines | Add the following variables to your Azure secret variables:
|
Bitbucket Pipelines | Add the following variables to your Bitbucket workspace variables:
|
CircleCI | Add the following variables to the CircleCI project settings:
|
Jenkins | Add the following variables to your Jenkins Global Credentials:
Note: Aqua supports integrating with Jenkins pipelines of both the types: Multibranch Pipeline and Pipeline. |
GitHub Actions | Add the following variables to your Organization Encrypted Secrets:
|
GitLab CI/CD | Add the following variables to your CI/CD variables:
Note: Make sure your CI/CD variables are not marked as protected, otherwise you will not be able to use them. |
b. Follow the instructions displayed on the UI for each CI build system to establish a connection with the pipeline.
c. Select either Pull request or Push, depending on whether you want to scan the specific code changes in a pull request or full code repository.
The CI Integration page for Azure Pipelines is shown here for your reference:
d. Copy the code block and add it to the workflow in your project or pipeline. Once the CI integration is successful, you will see the integrated code repository on the Code Repositories page.
Usage of the code block
As an example, a code block is shown below which should be added to the workflow in your Azure pipeline. Description to the important parameters is added below.
Code block:
trigger: none container: image: aquasec/aqua-scanner env: AQUA_KEY: $(AQUA_KEY) AQUA_SECRET: $(AQUA_SECRET) AZURE_TOKEN: $(AZURE_TOKEN) TRIVY_RUN_AS_PLUGIN: aqua # For http/https proxy configuration add env vars: HTTP_PROXY/HTTPS_PROXY, CA-CRET (path to CA certificate) steps: - checkout: self fetchDepth: 0 - script: | trivy fs --scanners config,vuln,secret . # To customize which severities to scan for, add the following flag: --severity UNKNOWN,LOW,MEDIUM,HIGH,CRITICAL # To enable SAST scanning, add: --sast # To enable npm/dotnet non-lock file scanning, add: --package-json / --dotnet-proj displayName: Aqua scanner
Usage of the keys and flags in the code block above:
- Aqua's Container image: As specified in the code block, you may use a specific aqua image, e.g., aqua-scanner. You will get all the aqua images from the docker hub aquasec repository. Specifically, you will get the aqua-scanner image from here. You can use any aqua image from the aquasec repository as required in the code block for your pipeline.
- Values for the AQUA_KEY, AQUA_SECRET, and AZURE_TOKEN keys will be pulled automatically from the Azure secret variables once they are added to the pipeline settings. For more information on the usage of these keys, refer to the table above.
- Value for TRIVY_RUN_AS_PLUGIN is always "aqua". Do not change it.
- (Optional) Add values for the keys HTTP_PROXY or HTTPS_PROXY and CA-CERT For the http or https proxy configuration.
- Pass the flag --severity and add values of the specific severities to scan for, e.g., UNKNOWN, LOW, MEDIUM, HIGH, CRITICAL.
- Pass the flag --sast to enable SAST scanning on the code repository.
- Pass the flag --package-json or --dotnet-proj to enable npm or dotnet non-lock file scanning respectively.
As per your selection of repository hosting platform, you will see a similar code block. You can add keys, flags, and values as explained above.
Integration with On-premises code repositories
Refer to Integration with On-Premises Code Repositories.
Delete an existing integration
To delete any existing integration:
- In the Actions column > options menu of the specific integration, click the Delete button. The Delete Integration dialog appears.
Did you find it helpful? Yes No
Send feedback