Version control
Connect GitLab, GitHub, Bitbucket or Azure DevOps to import repositories, scan every push and check pull requests.
A version control integration connects Portal to one GitLab, GitHub, Bitbucket or Azure DevOps server. With it you can:
- import repositories as assets (see Assets);
- run an audit of a repository on every push;
- comment on pull requests, set the commit status or close a pull request when it has findings.
Version control integrations need a paid license. See License.
Connect
Open the settings, then Version Control under Integrations, and click Add Version Control Integration.
-
Choose the Source Code Management System.
-
Enter the server URL and an access token. The form links to the page where you create the token.
System Token Permissions GitLab Personal access token apiandread_apiscopesGitHub Fine-grained token Discussions, Issues and Pull requests: read and write; Metadata: read-only. For commit statuses, also Commit statuses and Contents: read and write Bitbucket HTTP access token Project adminandRepository adminAzure DevOps Personal access token Code (Read)Turn off Verify SSL only for a server with a self-signed certificate.
-
Save. Token Health shows whether the token works. Errors from the server are logged on the integration’s page; Clear Log clears them.
The token’s owner is the Integration author. Audits started by pushes run on that user’s behalf.
Scan every push
Turn on Enable scan on commit push, then add the webhook to your version control:
- Copy the Webhook URL from the integration’s page. It is built from the external Portal URL and a token. To change the token, edit Webhook URL Token (UUID v4).
- In the repository or group settings of your version control, add a webhook with this URL and turn on push and pull request (merge request) events.
On each push, Portal runs an audit of the pushed branch of the repository’s asset, with the asset’s job sequence. A push to a repository that isn’t an asset yet adds it to the default product, Unsorted.
Check pull requests
A quality gate decides what happens when a pull request is opened or updated. It looks at the findings already reported for the pull request’s repository and branch, so turn on push scans too: they scan the branch before the quality gate looks at it.
Open the integration, scroll to Quality Gate and create one, or click Select from existing. An integration uses one quality gate. Azure DevOps integrations don’t support quality gates.
| Section | What it does |
|---|---|
| Choose finding attributes | which findings count, for example only verified findings of high severity |
| Pull request comment | comments on the pull request: Summary mode adds one comment that lists the findings, Inline mode comments on each line with a finding. You can delete the previous comment, comment when there are no findings and list findings from all branches |
| Commit status update | sets the commit status to Success or Failed depending on whether the commit has findings |
| Pull request closing | closes the pull request with your comment when it has findings. All branches closes it while any branch has findings, which blocks all merges |
Each action can use its own filters instead of the shared ones: click Define Own Filters in its section. The pull request’s repository and branch are always added to the filters.
Delay before applying any actions (minutes) on the integration’s page waits up to 10 minutes after the pull request event, so that the push scan can finish. During the wait, Portal posts a comment saying it will check the pull request.
Link findings to the source
A repository link config builds a link from a finding to the file and line in the repository. Open Repository Link Configs in the settings and create one with a Pattern that uses these variables:
| Variable | Value |
|---|---|
product_name | the product’s name |
subgroup | the subgroup, from the finding |
file_path | the path and file name, from the scanner |
file_name | the file name without its path |
line | the line number, from the scanner |
branch_name | the branch, tag or commit of the scanned code, from the finding |
The default config is used for repositories that don’t set their own. To use another one, choose it in the asset’s Repository Link Config.