Source Control REST API - v2
NEW IN RELEASE 79
The primary functions of the Source Control REST APIs are creating, updating, and deleting source control entries for the root organization, sub-organizations, and applications.
This is implemented with two separate endpoints one for all organizations (including the root), and a second one for applications. The API signatures between the two are similar and differences will be noted below.
The enablePullRequests
and enableStatusChecks
fields in the JSON payload were deprecated in IQ Server Release 124:
- enablePullRequests
was replaced with pullRequestCommentingEnabled
- enableStatusChecks
was replaced with statusChecksEnabled
The deprecated fields are scheduled for removal in March 2022.
If you use an IQ Server version prior to 124, you'll have to replace the deprecated field names in the examples below.
Step 1 - Create a source control entry
To create a source control entry use the following endpoint. To create one for an organization use organization
in the path, and for an application use application
in the path.
POST /api/v2/sourceControl/{organization|application}/{ownerId}
With the following JSON body
{ "token": "{scm access token}", "provider": "github", "repositoryUrl": "https://example.com/my-org/my-repo", "baseBranch": "master", "remediationPullRequestsEnabled": true, "pullRequestCommentingEnabled": true, "sourceControlEvaluationsEnabled": true }
- The
ownerId
parameter is required. For the/api/v2/sourceControl/organization/
endpoint it must be a valid organization ID (use "ROOT_ORGANIZATION_ID"
for the root organization). For the/api/v2/sourceControl/application/
endpoint it must be a valid application ID. - The
repositoryUrl
can only be specified for applications. Valid HTTP(S) and SSH URLs are accepted. - The
token
field is optional. It must be defined at one of the root organization, organization or application level. Each level inherits from the parent level and when present, will override any values set in the parents. Please see the Nexus IQ for SCM feature documentation for information on what permissions or scopes are required on the token. - The
username
field is optional and only allowed to be set on SCMs that require it. Currently this is Bitbucket Server and Bitbucket Cloud. - The
provider
field is required for the root organization and cannot be specified for other organizations or applications. Allowed values areazure
,github
,gitlab
, andbitbucket
. - The
baseBranch
field is required for the root organization. Organizations and applications inherit from the root unless overridden. - The
remediationPullRequestsEnabled
field is optional. Set totrue
to enable the Automated Pull Requests feature. - NEW IN RELEASE 125 The
pullRequestCommentingEnabled
field is optional. Set totrue
to enable the Pull Request Commenting feature. - NEW IN RELEASE 125 The
sourceControlEvaluationsEnabled
field is optional. Set totrue
to enable Nexus IQ triggered source control evaluations, which are the foundation of the Continuous Risk Profile feature.
Two formats are supported for SSH URLs: ssh://user@server/project-path.git
and user@server:project-path.git
.
On save all SSH URLs are converted to the HTTPS format. If an SSH URL is provided, subsequent retrievals will return the converted URL.
Step 2 - Get a source control entry
To get a source control entry use the following endpoint. To get for an organization use organization
in the path, and for an application use application
in the path.
GET /api/v2/sourceControl/{organization|application}/{ownerId}
- The
ownerId
parameter is required. For the/api/v2/sourceControl/organization/
endpoint it must be a valid organization ID (use "ROOT_ORGANIZATION_ID"
for the root organization). For the/api/v2/sourceControl/application/
endpoint it must be a valid application ID.
The response can contain the following fields
{ "id": "83af9dafc06946f9a82833eceb8425ed", "ownerId": "7e68069cbb228a05bbf89a2c2992a8bce45b1027", "repositoryUrl": null, "token": "#~FAKE~SECRET~KEY~#", "provider": null, "baseBranch": "master", "remediationPullRequestsEnabled": null, "pullRequestCommentingEnabled": null, "sourceControlEvaluationsEnabled": null, "statusChecksEnabled": null }
- Fields that do not contain a value are
null
. For organizations and application this indicates to inherit the configuration from the parent. Applications will inherit values from the parent organization and organizations will inherit from the root organization. - The
ownerId
field is required. For the/api/v2/sourceControl/organization/
endpoint it will be an organization ID. For the/api/v2/sourceControl/application/
endpoint it will be an application ID. - The
repositoryUrl
will only show for applications and will always benull
for organizations. - The
token
field is obfuscated if populated. - The
id
andstatusChecksEnabled
fields are internal fields.
Step 3 - Replace a source control entry
To replace a source control entry use the following endpoint. To replace one for an organization use organization
in the path, and for an application use application
in the path.
PUT /api/v2/sourceControl/{organization|application}/{ownerId}
- The
ownerId
parameter is required. For the/api/v2/sourceControl/organization/
endpoint it will be an organization ID. For the/api/v2/sourceControl/application/
endpoint it will be an application ID.
With the same JSON body as for POST
.
Step 4 - Delete a source control entry
To delete a source control entry use the following endpoint. To delete one for an organization use organization
in the path, and for an application use application
in the path.
DELETE /api/v2/sourceControl/{organization|application}/{ownerId}
- The
ownerId
parameter is required. For the/api/v2/sourceControl/organization/
endpoint it will be an organization ID. For the/api/v2/sourceControl/application/
endpoint it will be an application ID.
The response is an empty payload with a 204
(Success - no content) status.
Examples
Create a source control entry for the root organization
curl -u admin:admin123 \ -X POST http://localhost:8070/api/v2/sourceControl/organization/ROOT_ORGANIZATION_ID \ -H "Content-Type: application/json" \ -d '{ "token": "7e68069cbb228a05bbf89a2c2992a8bce45b1027", "baseBranch": "master", "provider": "github" }'
This example provides the token in addition to the two required fields
provider
andbaseBranch
.Create a source control entry for an organization
curl -u admin:admin123 \ -X POST http://localhost:8070/api/v2/sourceControl/organization/cc9798a095c64804b8ad5e1011794e0b \ -H "Content-Type: application/json" \ -d '{ "remediationPullRequestsEnabled": true, "baseBranch": "develop" }'
In this example
cc9798a095c64804b8ad5e1011794e0b
is the organization ID and it enables the pull request feature at the organization level, as well as overrides the pull request base branch to the value ofdevelop
.Create a source control entry for an application
curl -u admin:admin123 \ -X POST http://localhost:8070/api/v2/sourceControl/application/12a2011ed0094cebab55a4b99ba636ce \ -H "Content-Type: application/json" \ -d '{ "repositoryUrl": "https://github.com/my-org/my-repo", "baseBranch": "master" }'
In this example
12a2011ed0094cebab55a4b99ba636ce
is the IQ application ID, and it sets therepositoryUrl
for the application, as well as overrides thebaseBranch
attribute.Get a source control entry for an application
curl -u admin:admin123 -X GET http://localhost:8070/api/v2/sourceControl/application/12a2011ed0094cebab55a4b99ba636ce
The response will resemble:
{ "ownerId": "12a2011ed0094cebab55a4b99ba636ce", "repositoryUrl": "https://github.com/my-org/my-repo", "token": null, "provider": null, "baseBranch": "master", "remediationPullRequestsEnabled": true "pullRequestCommentingEnabled": true, "sourceControlEvaluationsEnabled": true, "statusChecksEnabled": true }
Note that a value of
null
generally indicates that the value is inherited from the parent organization.Replace a source control entry for an application
curl -u admin:admin123 \ -X PUT http://localhost:8070/api/v2/sourceControl/application/12a2011ed0094cebab55a4b99ba636ce \ -H "Content-Type: application/json" \ -d '{ "ownerId": "12a2011ed0094cebab55a4b99ba636ce", "repositoryUrl": "https://github.com/my-org/my-other-repo", "token": null, "provider": null, "baseBranch": "master", "remediationPullRequestsEnabled": true, "pullRequestCommentingEnabled": true, "sourceControlEvaluationsEnabled": true }'
This example takes the response from the
GET
and updates therepositoryUrl
to a new value.Delete a source control for an organization
curl -u admin:admin123 \ -X DELETE http://localhost:8070/api/v2/sourceControl/application/12a2011ed0094cebab55a4b99ba636ce
This example deletes the source control entry for the application
12a2011ed0094cebab55a4b99ba636ce
.