Nexus IQ Server Configuration

Overview

This page will walk you through adding your Source Control Management (SCM) Access Token to IQ Server. The IQ Server configuration options allow you to enable and disable the SCM Integration features. This setup consists of the following parts:

  • Base URL Configuration
  • Git Client Configuration (optional)
  • SCM Configuration in IQ Server
  • Testing Your Configuration

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

Prerequisites

IQ Server Configuration

Base URL Configuration

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

Base URL Configuration in IQ Server Version 138 and Later 

The Base URL is set using the Rest API. 

curl -u admin:admin123 -X PUT -H "Content-Type: application/json" -d '{"baseUrl": "http://127.0.0.1:8070", "forceBaseUrl": true}' http://localhost:8070/api/v2/config

Base URL Configuration in IQ Server Version 137 and Earlier 

Uncomment the BaseURL parameter in your config.yml 

baseUrl: http://nexus-iq-server.example.com/

Git Client Configuration

Git Client configuration is optional but recommended. Nexus IQ is bundled with JGit to work with no external software. JGit is a Java implementation of git that supports all IQ for SCM features. JGit does not support two git clone features that can improve performance: shallow clone and sparse checkout. Shallow clone lets us clone the least amount of git history. Sparse checkout lets us only check out files we need. These two git clone features improve performance with  large disk-space savings and reduced network traffic.

If a native git client is installed and available on the system path, then it will be preferred over JGit. This behavior can be overridden.

Nexus IQ Server uses git's repository clone feature for the following:

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

Native git is required in order to use SSH for git operations.

Set Git Client in IQ Server Release 140 and later

NEW IN RELEASE 140

Use the source control configuration REST API.

Set Git Client in IQ Server Release 139 and earlier

Specify the gitImplementation & gitExecutable in your config.yml:

sourceControl:
  gitImplementation: java
  gitExecutable: /usr/bin/git

Minimum Git Client Version

  • Native Git requires git v 2.16.0 or later.

Connect IQ Server to your SCM System

To connect Nexus IQ Server to your Source Control Management System:

  1. Login to Nexus IQ Server.
  2. Select Orgs and Policies.
  3. Navigate to the Root Organization.
  4. Scroll to Source Control Configuration.
  5. Click Edit Source Control Configuration.
  6. Select your Source Control Management System.
  7. 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.
  8. Enter your Default Branch (defaults to master)
  9. Enable or disable use SSH for Git operations.
    1. Disabled by default.
    2. Requires native git (see Configuring Git Client)
  10. Enable or disable automated remediation pull requests.
    1. This option is disabled by default. Must be enabled in order to use the Automated Pull Requests feature.
  11. Enable or disable pull request commenting.
    1. Enabled by default. Must be enabled in order to use the Pull Request Commenting feature.
  12. Enable or disable source control evaluations.
    1. Enabled by default. Must be enabled to use feature that includes evaluating the repository or pull requests.

All Source control configuration options can be overwritten at the organization and application level. This allows you to use multiple SCM providers and access tokens with IQ Server.

Application Source Control Configuration

Applications are configured like an organization with an additional field.

Applications require a Repository URL. Note:

  • This URL is used to connect to your Source Control System. 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.

Automatic SCM Configuration 

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.

See the Automatic SCM Configuration page for more information. 

Testing the Configuration

NEW IN IQ SERVER RELEASE 97

To test the configuration:

  1. Navigate to an application with SCM Configured (it can inherit from a parent organization).
  2. Select Source Control Configuration.
  3. Click Test Configuration.

Testing the SCM Configuration is only available at the Application Level.


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.

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 requires no extra configuration. This is the least secure option. Only use this in a fully trusted environment.
  • The Git for Windows installer lets you use a bundled version of SSH, or use an external version. If the bundled SSH is selected, SSH will only be available in Git Bash. This requires IQ to run in that same context. With an external version of SSH, 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 requires that the SSH_AUTH_SOCK environment variable is properly set.