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 are azure, github, gitlab, and bitbucket.
  • The baseBranch  field is required for the root organization. Organizations and applications inherit from the root unless overridden.
  • The remediationPullRequestsEnabled  field is optional. Set to true to enable the Automated Pull Requests feature.
  • NEW IN RELEASE 125 The pullRequestCommentingEnabled  field is optional. Set to true to enable the Pull Request Commenting feature.
  • NEW IN RELEASE 125 The sourceControlEvaluationsEnabled  field is optional. Set to true 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 be null for organizations.
  • The token field is obfuscated if populated.
  • The id and statusChecksEnabled 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

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

  2. 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 of develop.

  3. 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 the repositoryUrl for the application, as well as overrides the baseBranch  attribute.

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

  5. 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 the repositoryUrl to a new value.

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