Source Control Configuration

NEW IN IQ SERVER RELEASE 79

Note: While the term 'pull request' is used throughout this documentation, the equivalent terminology in GitLab is 'merge request'.


Setting up Nexus IQ for SCM

The IQ Server Base URL must be configured for this feature to work properly.

Required Token Permissions

FeatureAzure DevOpsBitbucket CloudBitbucket ServerGitHubGitLab
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/AN/A

Steps to Use SCM Features

Follow the steps listed below to enable automated pull requests and automated commit feedback:

Create an access token for your source control management (SCM) system

Azure DevOps

In Azure DevOps, create a personal access token:

  1. Log in to your organization in Azure DevOps
  2. From your home page, open your user settings
  3. On the  User Settings  menu select  Personal access tokens.
  4. Click the  + New Token button

5. Name your token and select All accessible organizations. Choose an expiry date for your token.

Important! If you do not select All accessible organizations, the Easy SCM Onboarding feature will not work.


6. Select the scopes for this token to authorize for your specific tasks. For the full features of IQ SCM support enable Code: Read & Write and then select Create.

See this explanation for details of Azure DevOps scopes

7. When you're done, make sure to copy the token and save it somewhere safe for later use. Once you leave the generate token dialog it won't be shown again for your security.

Bitbucket Cloud

  1. Log into Bitbucket Cloud.
  2. In the bottom left click your avatar and choose Bitbucket settings.
  3. In the Settings menu choose App passwords.
  4. Click the Create app password button.
  5. Choose a label for the token.
  6. Click Create.
  7. Save the app password somewhere safe. Once you leave or refresh the page you won’t be able to access it again.
  8. Note that for Bitbucket Cloud the username for the account is also required.


See this article for more information on Bitbucket Cloud App passwords.

Bitbucket Server

  1. Log into Bitbucket Server.
  2. In the top right click your avatar and choose Manage Account.
  3. In the left menu choose Personal access tokens.
  4. Click the Create a token button.
  5. Choose a name for the token.
  6. Click Create.
  7. Save the personal access token somewhere safe. Once you leave or refresh the page you won’t be able to access it again.
  8. Note that for Bitbucket Server the username for the account is also required.

See this article for more information on Bitbucket Server Personal Access Tokens.

GitHub

In GitHub create a personal access token:

  1. Log in to GitHub.
  2. In the upper-right corner click your avatar and select Preferences.
  3. In the left menu click Developer Settings.
  4. In the left menu click Personal access tokens.
  5. Click the Generate new token button.
  6. Save the personal access token somewhere safe for later use as once you leave the generate token dialog you will not be able to view it again.

See this explanation for details of GitHub scopes.

GitLab

In GitLab, create a personal access token:

  1. Log in to GitLab.
  2. In the upper-right corner click your avatar and select  Settings.
  3. On the  User Settings  menu select  Access Tokens.
  4. Choose a name and optional expiry date for the token.
  5. Select the api and write_repository scopes
  6. Click the   Create personal access token   button.
  7. Save the personal access token somewhere safe. Once you leave or refresh the page you won’t be able to access it again.




Inform IQ Server about your Source Control Configuration

Enter your Root Organization Source Control Configuration

  1. Login to Nexus IQ Server.
  2. Navigate to the Root Organization.
  3. Navigate to the Source Control configuration section.
  4. Click to open the Source Control Configuration edit page.
  5. Select your Source Control Management System.
  6. Optional Enter your access token. This will be used as the default access token for all organizations if entered here.
    1.  Enter the username for the token if required by your specific SCM choice.
  7. Enter your Default Branch (defaults to master)
  8. Enable or disable use SSH for Git operations.
  9. Enable or disable automated remediation pull requests .
  10. Enable or disable pull request commenting.
  11. Enable or disable source control evaluations.


Access tokens, username, default branch, using SSH for git operations, and enabling automated remediation pull requests, pull request commenting and source control evaluations can be overridden at the child organization and application levels.

Optional - Organization Source Control Configuration

Organizations may have their own SCM system, credentials, default branch, use SSH for git operations, automated pull request, pull request commenting and source control evaluations settings by overriding these values at the organization level.

When a policy evaluation request comes in for any IQ application in that same organization, Nexus IQ for SCM will use the specified access token to communicate status information back to your repository.

Application Source Control Configuration

Applications may have their own SCM system, credentials, default branch, ssh for git operations, automated pull request, pull request commenting and source control evaluations settings by overriding these values at the application level.

Applications must specify a Repository URL to enable any IQ for SCM features like automated commit feedback and automated pull requests. The Repository URL is entered manually here. Please consider the next points:

  • This URL will be used by IQ to properly set up the integration with the SCM. All SCM features use the SCM's REST APIs behind the scenes.
  • Enter a valid HTTP(S) clone URL for the Repository URL field. 

If you wish to enable SSH, please Check SSH for Git Operations section on this page.

With Automatic SCM Configuration turned on, the repository URL will be automatically discovered from the git project information and configured for the IQ application. Automatic SCM Configuration can be enabled via the configuration menu  in the toolbar.

Run a policy evaluation

Policy evaluations can originate from your CI environment, such as Jenkins, utilizing the IQ CLI directly or one of the Nexus IQ plugins provided for your respective CI system.  See this page for more information: https://help.sonatype.com/integrations/nexus-and-continuous-integration

You can also run a policy evaluation using the Nexus IQ command-line interface (CLI) directly, as described here: https://help.sonatype.com/integrations/nexus-iq-cli

The Nexus IQ client tooling will determine the commit hash and repository details for the given build and include that information in the policy evaluation request sent to the IQ server.

In order to automatically configure applications for source control integration, the Automatic Source Control Configuration system preference must be enabled and the user initiating the policy evaluation (could be a special user created to represent a CI system) must have the Evaluate Applications permission for the target application.

More details about how to enable Automatic Source Control Configuration can be found  here.

Optional: Configure Git Client

Git repository cloning is required for the following IQ for SCM features:

  • Automated Pull Requests,
  • Pull Request Commenting,
  • Instant Risk Profile
  • Continuous Risk Profile.

IQ for SCM features work without any additional software by using the bundled JGit application library. JGit is a Java implementation of git that supports all git functionality necessary for IQ for SCM.

JGit does not support two git clone features that can improve performance:  shallow clone  and  sparse checkout. Shallow clones allow us to clone the minimal amount of git history.  Sparse checkouts allow us to checkout only the necessary files to enable IQ for SCM features. These two git clone features provide large disk-space savings, increased time performance, and reduced network traffic.

If a native git client is installed and available on the system path, then it will be preferred over JGit. If you are having problems with native git, this behavior can be  overridden in the config.yml by forcing the usage of java git (JGit). Note that native git is required in order to use SSH for git operations.

sourceControl:
  gitImplementation: java

Git Executable

If a native git client is installed but is not on the system path, the fully qualified path to the executable can be specified in the config.yml file.

sourceControl:
  gitExecutable: /usr/bin/git

Minimum Git Client Version

If the native git client is installed and available on the path it is preferred. The minimum git version that has been tested is version 2.16.0.

SSH for Git Operations

NEW IN IQ SERVER RELEASE 126

SSH can now be used for Git operations such as the clone, fetch, and push. To enable SSH, select the option Use SSH for Git Operations in the configuration screen. 

On Root Organization:


On a Child Organization or an Application:

SSH requires native git and a properly configured SSH key that is available to IQ. Configuring an SSH key is beyond the scope of this help document. Please consult your security or operations team.

Some important notes

  • Using a passwordless SSH key is the simplest option, and requires no extra configuration. However this is considered the least secure option as anyone who has access to the system can then access what the SSH key can access. Only use this in a fully trusted environment.
  • The Git for Windows installer provides an option to choose a bundled version of SSH, or to use an external (or previously installed version). If the former is chosen then SSH will only be available in Git Bash meaning that IQ would have to be running in that context. If the latter is chosen, then the SSH key should be configured per the chosen implementation (e.g. OpenSSH for Windows, Putty)
  • On Linux most traditional setups should work as long as the context of the SSH agent is available to IQ. Sometimes this will involve ensuring that the SSH_AUTH_SOCK environment variable is properly set and available.

Protecting the Target Branch

In some source control systems, the target branch can be protected from merges with a failing IQ Policy Evaluation as described in the appropriate section below for your SCM system.

Protecting the Target Branch in Azure DevOps

To protect your target branch on Azure DevOps, you will need to create and configure a Branch Policy.

1. Navigate to Repos → Branches in the left menu, and find the branch that you want to configure the policy on (typically main or  develop ). From the context menu, select the  Branch policies  option


2. Scroll down to find  Status checks. Select the  +  button

3. Fill the form with the next information

Status to check * → Security/IQ Policy Evaluation

Policy requirement → Required

The rest of the values can use the default options


Here is a link with more information about how to configure a branch policy in AzDO:

https://docs.microsoft.com/en-us/azure/devops/repos/git/pr-status-policy?view=azure-devops

Protecting the Target Branch in Bitbucket Cloud

Bitbucket Cloud has two options for protecting the target branches from merges with a failing IQ Policy Evaluation.

  1. For all accounts, users get notified when they don't have that number of successful builds for the most recent commit.
  2. For premium accounts, users won't be able to merge if their pull request has unresolved merge checks

Click Settings, then Branch permissions, then Add a branch permission.

In the Add a branch permission dialog, select the desired branch option as well as the desired write access and merge access. In the Merge checks section select the option Check the last commit for at least 1 successful build and no failed builds.

This will inform users that the requirements are not fulfilled when trying to merge, but it will not prevent the merge.



Premium accounts have the additional ability to prevent the merge.

This will prevent users from merging a pull request with a failed build.


See these pages for more information:


Protecting the Target Branch in Bitbucket Server

The target branch can be protected from merges with a failing IQ Policy Evaluation by configuring a Merge check. Merge checks are a repository-wide setting and can also be enforced for all repositories.


Click the drop-down next to Minimum successful builds and choose Enabled. In the next dialog choose the desired minimum number of successful builds.

See this page for more information: https://confluence.atlassian.com/bitbucketserver/checks-for-merging-pull-requests-776640039.html

Protecting the Target Branch in GitHub

The target branch can be protected from merges with a failing IQ Policy Evaluation by configuring a branch protection rule in the repository's settings under Branches.

In the branch protection rule:

  • Add a new rule or edit an existing rule. 
  • Check Require status checks to pass before merging. 
  • Check IQ Policy Evaluation.
  • Save Changes


The IQ Policy Evaluation status check will not appear in the list of status checks found in the last week for this repository until the first policy evaluation status has been added to the repository.

493

See this page for more information: https://help.github.com/en/github/administering-a-repository/enabling-required-status-checks

Protecting the Target Branch in GitLab

GitLab projects can be configured to prevent merge requests from being merged if their pipeline did not succeed.  A failing IQ policy evaluation will cause the pipeline to fail, which in turn will prevent the merge request from being able to be merged.  You can enable this feature via the project settings as shown below.  See this page for more information:  https://docs.gitlab.com/ee/user/project/merge_requests/merge_when_pipeline_succeeds.html#only-allow-merge-requests-to-be-merged-if-the-pipeline-succeeds


Testing the Configuration

NEW IN IQ SERVER RELEASE 97

To test the configuration for pull request support, click the 'Test Configuration' button in the application source control configuration screen.

The 'Test Configuration' button is available once any changes have been saved with the 'Update' button.

There are three checks that are run:

  • Is the configuration complete? This check ensures that are required configuration options are in place. This includes all required options, some of which may be inherited from the organization.
  • Is the repository private? Repositories must be private or internal to enable all SCM features.  Support for public repositories is limited.
  • Does the token have sufficient permissions? This check will ensure the provided token has the necessary permissions or privileges to create pull requests. See the required token permissions section above for full details.