IQ Server Configuration

The IQ Server configuration options let you enable or disable SCM integration features. The setup includes the following parts:

Base URL configuration
Git client configuration (optional)
Connect IQ Server to the SCM system
Test your configuration

You can use Secure Shell (SSH) for Git operations such as cloning, fetching, and pushing.

The term pull request is equivalent to merge request in GitLab terminology.

Prerequisites

An access token for any of the following Source Control Management (SCM) 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.

Example:

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

Base URL Configuration in IQ Server Version 137 and Earlier

Uncomment the BaseURL parameter in your config.yml

Example

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

Git Client Configuration

Git Client configuration is optional but recommended. Sonatype IQ Server includes JGit, a Java-based Git implementation that supports all SCM features without external software.

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.

When the IQ Server uses Native Git, it supports shallow clones and sparse checkouts without additional configuration.

Tip

If a native Git client is installed and available on the system path, IQ will prefer it over JGit. This behaviour can be overridden.

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

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

Note

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

Set Git Client in IQ Server

Use the Source Control Configuration REST API.

For prior versions, specify the gitImplementation and gitExecutable in your config file:

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

Minimum Git Client Version

Native Git requires git v 2.16.0 or later.

GPG Commit Signing Configuration

GPG (GNU Privacy Guard) commit signing allows IQ Server to cryptographically sign commits created during automated remediation and pull-request creation.

This ensures commit authenticity and enables the Verified badge on commits in your Source Control Management (SCM) system.

Prerequisites:

GPG must be installed on the IQ Server host.

Configure the GPG Agent

To enable automated passphrase handling, configure the GPG agent:

mkdir -p ~/.gnupg
echo "allow-preset-passphrase" >> ~/.gnupg/gpg-agent.conf
gpgconf --kill gpg-agent

The agent restarts automatically on the next GPG operation.

Generate the Key Pair

Run:

gpg --full-generate-key

Suggested values (adapt as needed):

Prompt	Recommendation
Key type	RSA and RSA
Key size	4096 bits
Expiration	Based on policy (e.g. 2 years or no expiration)
Real name	Nexus IQ Server or automation account name
Email address	Must match `commitEmail` in IQ Server
Comment	Optional (“Automated commit signing”)
Passphrase	Optional (but recommended for security)

List and Export Your GPG Key

gpg --list-secret-keys --keyid-format=long

Example output:

sec   rsa4096/ABCD123456789012 2025-01-15 [SC] [expires: 2027-01-15]
         1234567890ABCDEF1234567890ABCDEF12345678
uid           [ultimate] Nexus IQ Server <nexus-iq@yourcompany.com>
ssb   rsa4096/9876543210FEDCBA 2025-01-15 [E] [expires: 2027-01-15]

Here the key ID is ABCD123456789012.

Configure GPG in IQ Server

Use the Source Control Configuration REST API to set the GPG signing properties.

curl -u admin:admin123 -X PUT \
     -H "Content-Type: application/json" \
     -d '{
       "commitEmail": "nexus-iq@yourcompany.com",
       "gpgSigningKey": "ABCD123456789012",
       "gpgPassphrase": "your-secure-passphrase"
     }' \
     http://localhost:8070/api/v2/config/sourceControl

Note

The commitEmail must match the email on the GPG key.
The key must exist in the GPG keyring of the user running IQ Server.
If your key has no passphrase, omit gpgPassphrase or set it to null.

Configure GPG in Your SCM System

After configuring GPG in IQ Server, you need to add the public GPG key to your SCM system to verify signed commits.

Export your public key using the following command:

gpg --armor --export ABCD123456789012

Copy the entire output, including the lines:

   -----BEGIN PGP PUBLIC KEY BLOCK-----
...
   -----END PGP PUBLIC KEY BLOCK-----

Add the copied key to your SCM system as described below.

GitHub

Go to Settings → SSH and GPG keys.
Click New GPG key.
Paste your copied key into the field.
Click Add GPG key.

GitLab

Click your avatar in the top-right corner.
Select Preferences → GPG Keys.
Paste your copied key.
Click Add key.

Bitbucket (Server or Cloud)

Click your profile picture in the upper-right corner.
Select Manage account (Cloud) or Manage account/View profile (Server/Data Center).
In the left sidebar, click GPG keys.
Click Add key, paste your copied key, and click Save.

Azure DevOps

Azure DevOps does not yet display verified commits in the UI, but signed commits are recorded and verifiable via Git tools.

Verifying GPG Signing

After configuration:

Push an automated commit or pull request.
In your SCM, look for a Verified badge on the commit.
You can also verify locally:
```
git log --show-signature
```

Configure IQ Server With Your SCM System

Configuring Sonatype IQ Server with a Source Control Management (SCM) system requires the Edit IQ elements permission.

Log in to Sonatype IQ Server.
Select Orgs and Policies.
Navigate to the Root Organization.
Scroll to Source Control Configuration.
Click the button under Configuration to open the settings for your SCM.
Select your Source Control Management System.
Enter your access token. This will be used as the default access token for all organizations.

Note Make sure your token includes the minimum required scopes for your SCM (for example, repo read/write on GitHub, Code & Pull requests on Bitbucket). For a detailed list of provider-specific permissions, see Create an Access Token.
Enter your Default Branch (defaults to master)
Enable or disable Use SSH for Git operations.
1. Disabled by default
2. Requires native Git
Enable or disable Automated Remediation with GoldenPRs™. Automated Remediation with GoldenPRs™ automatically generates pull requests with remediation suggestions for policy violations found on the default branch. It helps keep dependencies secure and up to date by recommending safe, non-breaking versions, reducing manual remediation effort.
1. This option is disabled by default. It must be enabled in order to use the Automated Pull Requests feature

These settings apply only to automated remediation pull requests (Auto PRs). - Close AutoPRs when one or more required checks fail: Pull requests often include one or more mandatory checks that run on each commit. If any of these required checks fail, the Auto PR closes automatically. This prevents failing pull requests from remaining open unnecessarily. Available for Github and Gitlab repositories. - Close AutoPRs that haven’t been merged or closed after: Sometimes, pull requests remain open for a long time without being merged or closed manually. This option lets you configure Auto PRs to close automatically after a specified number of days. It helps keep your repository clean by removing stale pull requests. Available for all supported SCM providers (GitHub, GitLab, Azure DevOps, Bitbucket Cloud and Bitbucket Data Center). 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. 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. 14. Enable or disable Manual Pull Requests. 1. Enabled by default. When suggested version updates are available, displays an option to manually create a pull request targeting the default branch. 15. Click the Create or Update button.

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

An application is configured like an organization with an additional field: Repository Clone URL.

Enter a valid HTTP(S) URL for the Repository Clone URL field.

This URL is used to connect to your SCM. All SCM features use the SCM's REST APIs behind the scenes.

Note

Changing the Repository Clone URL resets the existing source control data for the application. This action cannot be undone.

Resetting the Repository Clone URL results in:

Deletes IQ Server’s internal database records of pull request comments for the application
Deletes stored branch commit history
Deletes the local Git checkout directory
Resets poll time and error counts

Note

If you want to enable SSH, check SSH for Git operations.

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. Enable Automatic SCM Configuration via the configuration menu in the toolbar.

See the Automatic SCM Configuration page for more information.

Testing the Configuration

To test the configuration:

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

Note

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

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 this requires that the SSH_AUTH_SOCK environment variable is properly set.