Source Control Configuration
NEW IN IQ SERVER RELEASE 79
Note: While the term 'pull request' is used throughout this documentation, the equivalent terminology in GitLab is 'merge request'.
Setting up Nexus IQ for SCM
Configure the IQ Server Base URL
SCM features will not work unless the IQ Server Base URL is configured.
Required Token Permissions
|Feature||Bitbucket Cloud||Bitbucket Server||GitHub||GitLab|
|Automated Commit Feedback|
|Automated Pull Requests||under||under||api + write_repository|
|Pull Request Commenting||under||api|
|Pull Request Line Commenting||under||api|
|Bitbucket Code Insights||under||N/A||N/A|
Steps to Use SCM Features
Follow steps listed below to enable automated pull requests and automated commit feedback:
Create an access token for your source control management (SCM) system
In GitHub create a personal access token:
In GitLab, create a personal access token:
Inform IQ Server about your Source Control Configuration
Enter your Root Organization Source Control Configuration
Access tokens, username, enabling automated pull requests and the default branch can be overridden at the child organization and application levels.
Optional - Organization Source Control Configuration
Organizations may have their own default credentials, enable automated pull request setting, and default branch by overriding these values at the organization level.
When a policy evaluation request comes in for any IQ application in that same organization, Nexus IQ for SCM will use the specified access token to communicate status information back to your repository.
Application Source Control Configuration
Applications may have their own credentials, enable pull request setting and default branch by overriding these values at the application level.
Applications must specify a Repository URL to receive automated commit feedback and automated pull requests. The Repository URL is entered manually here.
Valid HTTP(S) and SSH repository URLs are accepted. Two formats are supported for SSH URLs:
On save all SSH URLs are converted to the HTTPS format and the Repository URL will show the converted value.
Full support for SSH URLs is coming soon. Note that Bitbucket Server currenly only supports HTTP(S) URLs at this time.
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 on the toolbar.
Run a policy evaluation
Policy evaluations can originate from your CI environment, such as Jenkins, utilizing the IQ CLI directly or one of the Nexus IQ plugins provided for your respective CI system. See this page for more information: https://help.sonatype.com/integrations/nexus-and-continuous-integration
You can also run a policy evaluation using the Nexus IQ command line interface (CLI) directly, as described here: https://help.sonatype.com/integrations/nexus-iq-cli
The Nexus IQ client tooling will determine the commit hash and repository details for the given build and include that information in the policy evaluation request sent to IQ server.
In order to automatically configure applications for source control integration, the Automatic Source Control Configuration system preference must be enabled and the user initiating the policy evaluation (could be a special user created to represent a CI system) must have the Evaluate Applications permission for the target application.
More details about how to enable Automatic Source Control Configuration can be found here.
Protecting the Target Branch
In some source control systems the target branch can be protected from merges with a failing IQ Policy Evaluation as described in the appropriate section below for your SCM system.
Protecting the Target Branch in Bitbucket Cloud
Bitbucket Cloud has two options for protecting the target branches from merges with a failing IQ Policy Evaluation.
- For all accounts, users get notified when they don't have that number of successful builds for the most recent commit.
- For premium accounts, users won't be able to merge if their pull request has unresolved merge checks
Click Settings, then Branch permissions, then Add a branch permission.
In the Add a branch permission dialog, select the desired branch option as well as the desired write access and merge access. In the Merge checks section select the option Check the last commit for at least 1 successful build and no failed builds.
This will inform users that the requirements are not fulfilled when trying to merge, but it will not prevent the merge.
Premium accounts have the additional ability to prevent the merge.
This will prevent users from merging a pull request with a failed build.
See these pages for more information:
Protecting the Target Branch in Bitbucket Server
The target branch can be protected from merges with a failing IQ Policy Evaluation by configuring a Merge check. Merge checks are a repository-wide setting and can also be enforced for all repositories.
Click the drop-down next to Minimum successful builds and choose Enabled. In the next dialog choose the desired minimum number of successful builds.
See this page for more information: https://confluence.atlassian.com/bitbucketserver/checks-for-merging-pull-requests-776640039.html
Protecting the Target Branch in GitHub
The target branch can be protected from merges with a failing IQ Policy Evaluation by configuring a branch protection rule in the repository's settings under Branches.
In the branch protection rule add a new rule or edit an existing rule. Next, check Require status checks to pass before merging. Finally, check IQ Policy Evaluation.
The IQ Policy Evaluation status check will not appear in the list of status checks found in the last week for this repository until the first policy evaluation status has been added to the repository.
See this page for more information: https://help.github.com/en/github/administering-a-repository/enabling-required-status-checks
Protecting the Target Branch in GitLab
GitLab projects can be configured to prevent merge requests from being merged if their pipeline did not succeed. A failing IQ policy evaluation will cause the pipeline to fail, which in turn will prevent the merge request from being able to be merged. You can enable this feature via the project settings as shown below. See this page for more information: https://docs.gitlab.com/ee/user/project/merge_requests/merge_when_pipeline_succeeds.html#only-allow-merge-requests-to-be-merged-if-the-pipeline-succeeds
Testing the Configuration
NEW IN IQ SERVER RELEASE 97
To test the configuration for pull request support, click the 'Test Configuration' button in the application source control configuration screen.
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? Pull requests only work on private repositories. This check will ensure the repository is private. See the Automated Pull Requests documentation for full details.
- 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.