Nexus IQ Server Configuration

Overview

The IQ Server configuration options allow you to enable and disable the SCM Integration features. This setup consists of the following parts:

You can use Secure Shell (SSH) for Git operations such as clone, fetch, and push.

Note: The term 'pull request' is equivalent to 'merge request' used in GitLab terminology.

Prerequisites

An access token for any of the following Source Control Management Systems:

IQ Server Configuration

Base URL Configuration

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 the 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. It must be enabled in order to use the Automated Pull Requests feature.
  11. Enable or disable pull request commenting.
    1. Enabled by default. It 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 the feature that includes evaluating the repository or pull requests.
  13. NEW IN RELEASE 161 Enable or disable automated commit feedback.
    1. Enabled by default. Must be enabled to allow the creation of commit statuses based on source control evaluation results.

All Source control configuration options can be overwritten at the organization and application levels. 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


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


SSH can be used for Git operations such as 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.