Source Control Configuration

NEW IN RELEASE 79

Setting up Nexus IQ for SCM

Configure the IQ Server Base URL

SCM features will not work unless the IQ Server Base URL is configured.

Steps to Use SCM Features

The steps required to enable automated pull requests (supported in GitHub) and automated commit feedback (supported in GitHub and GitLab) are as follows:

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

GitHub Access Token

Permission for IQ server to communicate status to your GitHub instance is granted via a GitHub access token with the repo:status scope enabled.  In GitHub, generate the access token in Settings / Developer settings / Personal access tokens.

Reminder: the token needs to have the  repo:status scope enabled for automated commit feedback and repo scope enabled for automated pull requests.  Copy the access token somewhere safe for later use as once you leave the generate token dialog you will not be able to view it again.

GitLab Access Token

The automated pull request feature is not yet supported for 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. Choose the api scope.
  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 Access Token Provider.
  6. Optional Enter your access token. This will be used as the default access token for all organizations if entered here.
  7. Enable or disable automated Pull Requests.
  8. Enter your Default Branch (defaults to master)

Access tokens, enabling automated pull requests and the default branch can be overridden at the child organization and application levels.

Optional - Organization Source Control Configuration

Organizations may have their own default access token, enable automated pull request setting, and default branch 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 access token, enable pull request setting and default branch by overriding these values at the application level.

Applications must specify a Repository URL to receive automated commit feedback and automated pull requests. The Repository URL is entered manually here.

Valid HTTP(S) and SSH repository URLs are accepted. Two formats are supported for SSH URLs: ssh://user@server/project-path.git and user@server:project-path.git.

On save all SSH URLs are converted to the HTTPS format and the Repository URL will show the converted value.

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  on 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 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.

Protecting the Target Branch

In GitHub, 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. See this page for more information: https://help.github.com/en/github/administering-a-repository/enabling-required-status-checks

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.  Next, check Require status checks to pass before merging.  Finally, check IQ Policy Evaluation.

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.

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