Source Control Configuration
Source Control Configuration
Sonatype Lifecycle can connect to your Source Control Management (SCM) system with an access token to scan your projects during the development phase. The access token can be set at the Root Organization level. This page provides the configuration steps for SCM.
Note
The Configuring Base URL must be configured for Source Control Features to function.
Note
For Sonatype IQ Server High Availability (HA) deployments, the SCM source-control directory must be configured on shared storage that is accessible by all HA nodes.
For more information, see IQ Server High Availability Installation.
Configuration Checklist
Follow the steps below to connect your SCM system to Sonatype Lifecycle.
- Create SCM Access Token
- Configure base URL in IQ Server
- Navigate to Source Control at the Root Organization
- Select Source Control Management System
- Add your SCM Access Token (created in step 1) to enable Lifecycle features
- Enter the Default Branch
- Toggle Use SSH for Git Operations
- Toggle Automated Pull requests
- We recommend disabling it when used with Easy SCM Onboarding
- Toggle Pull Request Commenting
- Recommended for all repositories.
- Toggle Source Control Evaluations
- Recommended for all repositories.
- Select Automated Commit Feedback
- If you are importing a large number of applications, this may cause you to hit SCM rate limits. In such scenarios, we recommend disabling Automatic Commit Feedback, during the import. You can enable this after the import, for all the repositories.
- Optional: Create separate access tokens for IQ Server Organizations using different SCM Systems
- Optional: Configure additional SCM Features
SCM Feature Configuration
The table below shows where the SCM feature is configured.
| Feature | Configuration |
|---|---|
| Automatic Pull Requests | Configured at the Organization or Application level. - Inherited by default (disabled by default at the root organization) |
| SSH Operations | Configured at the Organization or Application level. - Inherited by default (disabled by default at the root organization) |
| Pull Request Commenting | Configured at the Organization or Application level. - Inherited by default (enabled by default at the root organization) |
| Pull Request Line Commenting | Enabled with Pull Request Commenting. |
| Source Control Evaluations | Configured at the Organization or Application level. - Inherited by default (enabled by default at the root organization) |
| Automated Commit Feedback | Configured in SCM Provider. Configured at the Organization or Application level. - Inherited by default (enabled by default at the root organization) |
| Automatic SCM Configuration | Configured on the page accessed through Settings Menu. |
| Easy SCM Onboarding | Application import feature. Requires SCM Access token configured. |
| Bitbucket Code Insights | Configured with Pull Request Commenting |
| Automatic Role Assignment | Configured at the organization level using the Source Control REST API |
Create Access Token
Select your SCM provider below for information on creating an access token and configuring your SCM System for use with Sonatype Lifecycle.
Required Token Permissions
| Feature | Azure DevOps | Bitbucket Cloud | Bitbucket Server | GitHub | GitLab |
|---|---|---|---|---|---|
| Automated Commit Feedback | Code: Read & Write | Read under Repositories | Read under Repositories | repo:status | api |
| Automated Pull Requests | Code: Read & Write | Write under Pull Requests | Write under Repositories | repo | api + write_repository |
| Pull Request Commenting | Code: Read & Write | Write under Repositories | repo | api | |
| Pull Request Line Commenting | Write under Repositories | repo | api | ||
| Bitbucket Code Insights | Write under Repositories | N/A | N/A | ||
| Automatic Role Assignment | user:email read:user |
Supported SCM Authentication
For enhanced security and following industry best practices, basic authentication (username and password) is either deprecated or not recommended for most Source Control Management (SCM) providers. We recommend using secure alternatives such as Personal Access Tokens (PATs), OAuth, or SSH keys for authenticating with your SCM systems.
Dealing with SCM API rate limits
When an SCM system's API interacts with Nexus IQ, the SCM system enforces some form of limitation on the volume and frequency of interaction with their APIs; GitHub appears to be the most restrictive. GitHub limits API requests to 5000 per hour per user and specifies at least a one-second delay between requests. As the number of applications that IQ Server manages increases, the workload demanded of the SCM API also increases. This translates to a delay between, for example, the time the workload is initially processed and the time before a comment is added to a pull request.
Since the SCM system API limitations are per user, organizations with hundreds or thousands of repositories should create multiple users/access tokens and use different tokens for different sub-organizations in IQ Server. This allows IQ Server to perform more work in parallel with the SCM system. The additional tokens must be for distinct SCM users — multiple tokens for the same user will not help since the API rate limits apply at the user level and not the token level. A reasonable starting point would be one user/token for every 500 repositories.
Troubleshooting
Special Characters in Repository Names
Sonatype has special character restrictions on repository names for security reasons. The special characters that are restricted include:
/ : \ ~ & % ; @ ' " ? < > | # $ * } { , + ] [
The repository names cannot start with an underscore ( _ ), start or end with a period (.), or be a system reserved name.
Some SCM providers do not have similar restrictions and allow special characters in repository names. This could lead to errors during onboarding the applications from the SCM system such as the example below:
SourceControl repositoryUrl is invalid: Invalid project URL. Project URL cannot contain any of the characters: ;$!*&|()[]<>.