Source Control REST API

Source Control REST API can be used to:

Create, update, and delete 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.
Automatically assign the developer role to all contributors of the associated repository, who are registered IQ users, for a given application. See Automatic Role Assignment.
Map existing SCM user credentials (GitHub) to Lifecycle users.

Warning

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

If you use an IQ Server version prior to 124, you'll have to replace the deprecated field names in the examples below.

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. See the Sonatype 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 required for Bitbucket Server, Bitbucket Cloud and Azure DevOps.
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.
The pullRequestCommentingEnabled field is optional. Set to true to enable the Pull Request Commenting feature.
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.

Note

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.

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 applications, this indicates inheriting 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.

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.

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.

Automatic Role Assignment (GitHub)

You can grant any role to all contributors of the associated repository, on a given application, automatically, if the following conditions are met:

The source control should be configured for the application and it should have an authentication token.
The scope of the token generated from the SCM configuration page must have one of the following scopes:
user:email or read :user.
The contributors to the repository should have a corresponding account in IQ that satisfies the match criteria of the user mapping in the SCM (GitHub).
The user calling the API should have Edit Access Control permission for the given application.
A user mapping configuration is inherited from a parent in the hierarchy or is provided as an optional payload.

The role specified in the user mapping will be automatically assigned to all contributors of the repository, who have met the matching criteria specified in the user mapping configuration.

Note

This capability is currently offered only for GitHub repositories.

Example

Providing the user mapping configuration in the request payload is optional.

If a user mapping configuration payload is provided, it will be used to match the users and assign the specified role, based on the configuration. See Configure User Mappings for an example of user mapping configuration payload.
If a user mapping configuration payload is not provided, a configured user mapping will be used. User mapping can be configured on the parent organization.
If a user mapping configuration payload is not provided, and there is no user mapping configuration that can be inherited, the request will fail.

curl -u admin:admin123 \
  -X POST 'http://localhost:8070/api/v2/sourceControl/automaticRoleAssignment/my-public-app-id' \
  --data-raw '{"role":"developer","mappings":[{"from":"SCM_EMAIL","to":"IQ_EMAIL"},{"from":"SCM_FULLNAME","to":"IQ_FULLNAME"},{"from":"SCM_USERNAME","to":"IQ_USERNAME"},{"from":"GITLOG_FULLNAME","to":"IQ_FULLNAME"},{"from":"GITLOG_EMAIL","to":"IQ_EMAIL"}]}'

Response

The response is an array of all users that were found in GitHub and were successfully granted the developer role on the application.

Example

[
  "githubUser1",
  "githubUser2",
  "githubUser3",
  "githubUser4",
  "githubUser5",
  "githubUser6",
  "githubUser7"
]

Configure User Mappings (GitHub)

You can apply user mappings to an organization in Lifecycle using the POST method. The user mappings will be inherited by all organizations and applications under the organization specified.

POST /api/v2/sourceControl/automaticRoleAssignment/userMappings/{organizationId}

Request Body as JSON:

{
  "role": "developer",
  "mappings":  [
    {
      "from": "SCM_EMAIL",
      "to": "IQ_EMAIL"
    },
  ]
}

Example:

curl -u admin:admin123 \
  -X POST 'http://localhost:8070/api/v2/sourceControl/automaticRoleAssignment/userMappings/39cdb8dc95444802944545e3a6d8de8d' \
  --data-raw '{"role":"developer","mappings":[{"from":"SCM_EMAIL","to":"IQ_EMAIL"},{"from":"SCM_FULLNAME","to":"IQ_FULLNAME"},{"from":"SCM_USERNAME","to":"IQ_USERNAME"},{"from":"GITLOG_FULLNAME","to":"IQ_FULLNAME"},{"from":"GITLOG_EMAIL","to":"IQ_EMAIL"}]}'

Input parameter	Required	Description
organizationId	Yes	Must be a valid organization that exists in your Lifecycle instance. use `ROOT_ORGANIZATION_ID` for the root organization. If a user mapping for the organization already exists, it will be replaced with the new mappings. The user mapping will be inherited by all organizations and applications under the specified organizationId.
role	Yes	Indicates the name of the role in lowercase, without whitespaces. E.g. System Administrator should be entered as systemadministrator
mappings	Yes	Is an array of objects consisting of `from` and `to` fields. Refer to user mappings for details. Allowed values for `from` field are: SCM_USERNAME, SCM_EMAIL, SCM_FULLNAME, GITLOG_EMAIL, GITLOG_FULLNAME Allowed values for `to` field are: IQ_USERNAME, IQ_EMAIL, IQ_FULLNAME

Input parameter

Required

Description

organizationId

Yes

Must be a valid organization that exists in your Lifecycle instance.

use ROOT_ORGANIZATION_ID for the root organization.

If a user mapping for the organization already exists, it will be replaced with the new mappings.

The user mapping will be inherited by all organizations and applications under the specified organizationId.

role

Yes

Indicates the name of the role in lowercase, without whitespaces.

E.g. System Administrator should be entered as systemadministrator

mappings

Yes

Is an array of objects consisting of from and to fields. Refer to user mappings for details.

Allowed values for from field are:

SCM_USERNAME, SCM_EMAIL, SCM_FULLNAME, GITLOG_EMAIL, GITLOG_FULLNAME

Allowed values for to field are:

IQ_USERNAME, IQ_EMAIL, IQ_FULLNAME

Mapping GitHub Email Ids

Some users in GitHub may have their email Ids set to private or use personal email instead of the organization email. For such cases, we recommend using GITLOG_EMAIL to map the users email Id, instead of using SCM_EMAIL.

More about user mappings

Example 2: This example shows how to map public GitHub email Id to the email of email Id of an existing IQ/Lifecycle user.

{
  "from": "SCM_EMAIL",
  "to": "IQ_EMAIL"
}

You can use the usermappings endpoint to match GitHub users to existing IQ/Lifecycle users.
When multiple usermappings are specified in the request body, and the first mapping fails, the next user mapping will be attempted.

If duplicate usermappings are specified, an error message will be displayed as below:

There was a duplicate mapping GITLOG_FULLNAME:IQ_FULLNAME . Mappings should be unique

You can use any combination of the allowed values for the from and to fields.

Example 1:

{
  "from": "SCM_USERNAME",
  "to": "IQ_EMAIL"
},
{
  "from": "GITLOG_FULLNAME",
  "to": "IQ_USERNAME"
}

Some suggested user mappings are shown below:

{
  "from": "GITLOG_EMAIL",
  "to": "IQ_EMAIL"
},
{
  "from": "GITLOG_FULLNAME",
  "to": "IQ_FULLNAME"
},
{
  "from": "SCM_USERNAME",
  "to": "IQ_USERNAME"
},
{
  "from": "SCM_EMAIL",
  "to": "IQ_EMAIL"
},
{
  "from": "SCM_FULLNAME",
  "to": "IQ_FULLNAME"
}

Retrieve existing user mappings

Use the GET method to retrieve the SCM user mappings, by specifying the organization or application.

GET /api/v2/sourceControl/automaticRoleAssignment/userMappings/{ownerType}/{ownerId}

The input parameters ownerType and ownerId are required. Allowed values for ownerType are organization or application. ownerId is the internal id of the ownerType (organization or application).

Example:

curl -u admin:admin123 \
  -X GET 'http://localhost:8070/api/v2/sourceControl/automaticRoleAssignment/userMappings/organization/39cdb8dc95444802944545e3a6d8de8d'

Sample response:

{
  "organizationId": "80599b788da849a796c96e245770179f",
  "inherited": true,
  "userMapping": {
    "role": "developer",
    "mappings": [
      {"from": "GITHUB_EMAIL", "to": "IQ_USERNAME" },
      {"from": "GITLOG_EMAIL", "to": "IQ_EMAIL" },
      {"from": "GITHUB_FULLNAME", "to": "IQ_FULLNAME" }
    ]
  }
}

Response field	Description
organizationId	Indicates the organization id for which the user mappings were created.
inherited	Value is always `true` if the specified `ownerType` is application.
userMapping	Is an object containing `role` and `mappings` `role` indicates the role assigned to users during automatic role assignment. `mappings` contains all user mappings.

Response field

Description

organizationId

Indicates the organization id for which the user mappings were created.

inherited

Value is always true if the specified ownerType is application.

userMapping

Is an object containing role and mappings

role indicates the role assigned to users during automatic role assignment.

mappings contains all user mappings.

Delete existing user mappings

Use the DELETE method to delete existing SCM user mappings, by specifying the organization id for which the user mappings were created.

DELETE/api/v2/sourceControl/automaticRoleAssignment/userMappings/{organizationId}

The input parameter organizationId is required.