# 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:

- [Azure DevOps](https://help.sonatype.com/en/azure-devops-configuration.html "Azure DevOps Configuration")
- [Bitbucket Server](https://help.sonatype.com/en/bitbucket-configuration.html "Bitbucket Data Center Configuration")
- [Bitbucket Cloud](https://help.sonatype.com/en/bitbucket-cloud-configuration.html "Bitbucket Cloud Configuration")
- [Github](https://help.sonatype.com/en/github-configuration.html "GitHub Configuration")
- [Gitlab](https://help.sonatype.com/en/gitlab-configuration.html "GitLab Configuration")

## 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](https://git-scm.com/docs/git-clone) and [sparse checkout](https://git-scm.com/docs/git-checkout/). Shallow clone lets us clone the least amount of git history. Sparse checkout lets us only check out the [files we need.](https://help.sonatype.com/en/sparse-checkout-file-types.html "Understanding Sparse Checkout for SCM Scanning") 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](https://help.sonatype.com/en/source-control-configuration-rest-api.html "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 <nexus-iq@yourcompany.com>
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": "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`.

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

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.

01. Log in to **Sonatype IQ Server**.
02. Select **Orgs and Policies.**
03. Navigate to the **Root Organization**.
04. Scroll to **Source Control** **Configuration**.
05. Click the button under **Configuration** to open the settings for your SCM.
06. Select your **Source Control Management System**.
07. 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](https://help.sonatype.com/en/source-control-configuration.html#create-access-token "Create Access Token").
08. Enter your **Default Branch** (defaults to _master_)
09. 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

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](https://help.sonatype.com/en/iq-server-configuration.html#ssh-for-git-operations "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:

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.

|     |
| --- |
|  |

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](https://docs.microsoft.com/en-us/windows-server/administration/openssh/openssh_install_firstuse), 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.