Skip to main content

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.

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

  2. 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)

  3. 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 <[email protected]>
ssb   rsa4096/9876543210FEDCBA 2025-01-15 [E] [expires: 2027-01-15]

    Here the key ID is ABCD123456789012.

  4. 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": "[email protected]",
    "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.

  5. Configure GPG in Your SCM System

    After configuring GPG in IQ Server, you must 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.

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

  1. Log in to Sonatype IQ Server.

  2. Select Orgs and Policies.

  3. Navigate to the Root Organization.

  4. Scroll to Source Control Configuration.

  5. Click the button under Configuration to open the settings for your SCM.

  6. Select your Source Control Management System.

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

  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

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

      Screenshot_2025-08-27_155448.png

      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 Github, Gitlab and Azure DevOps repositories.

  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.

157680922.png

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

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 126655181.png 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.

Note

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

126655196.png

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.

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:

126655183.png

On a Child Organization or an Application:

126655184.png

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.