Sonatype Source Control API

openapi: 3.2.0
info:
  title: Sonatype Source Control API
  version: '1.0'
  description: 'Operations tagged Source Control across 2 of this provider''s published API definitions: sonatype-lifecycle-openapi.yml, sonatype-iq-openapi.yml. Each path carries the servers of the definition it was published in.'
security:
- BasicAuth: []
  BearerAuth: []
tags:
- description: 'Use this REST API to:


    Create, update and delete source control management (SCM) configuration for the root organization, sub-organizations and applications.


    Automatically assign the developer role to all contributors of the associated repository, who are registered IQ users.'
  name: Source Control
paths:
  /api/v2/sourceControl/automaticRoleAssignment/userMappings/{organizationId}:
    delete:
      description: 'Use this method to delete existing SCM user mappings for an organization.


        Permissions required: Edit IQ Elements'
      operationId: deleteUserMappings
      parameters:
      - description: Enter the organizationId.
        in: path
        name: organizationId
        required: true
        schema:
          type: string
      responses:
        '204':
          description: User mappings deleted successfully.
      tags:
      - Source Control
      summary: Delete user mappings
      x-summary-source: derived
    post:
      description: 'Use this method to apply user mappings from SCM (GitHub) to Lifecycle. The user mappings will be inherited by all child organizations and applications in the organization hierarchy. If a user mapping for an organization already exists, it will be replaced with new mappings provided here.


        Permissions required: Edit IQ Elements'
      operationId: addUserMappings
      parameters:
      - description: Enter the organizationId. Use `ROOT_ORGANIZATION_ID` for the root organization
        in: path
        name: organizationId
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SCMUserMappingsDTO'
        description: <ul><li>Specify the `role` in lowercase, without whitespaces.</li><li>`mappings` is an array of objects consisting of `from` and `to` fields.</li><li>Allowed values for the `from` field are `SCM_USERNAME`, `SCM_EMAIL`, `SCM_FULLNAME`, `GITLOG_EMAIL`, `GITLOG_FULLNAME`.</li><li>Allowed values for `to` field are `IQ_USERNAME`, `IQ_EMAIL`, `IQ_FULLNAME`.</li><li>Any combination of `from` and `to` fields can be used.</li></ul>
      responses:
        '204':
          description: User mappings applied successfully.<ul><li>When multiple user mappings are specified in the body, and the first mapping fails,  the next user mapping will be attempted.</li><li>If duplicate user mappings are specified, an error message will be displayed</li></ul>
      tags:
      - Source Control
      summary: Add user mappings
      x-summary-source: derived
  /api/v2/sourceControl/automaticRoleAssignment/userMappings/{ownerType}/{internalOwnerId}:
    get:
      description: 'Use this method to retrieve SCM user mappings for an organization or application.


        Permissions required: View IQ Elements'
      operationId: getUserMappingsByOwner
      parameters:
      - description: Enter the value for ownerType.
        in: path
        name: ownerType
        required: true
        schema:
          enum:
          - application
          - organization
          pattern: application|organization
          type: string
      - description: Enter the value for internal ownerId.
        in: path
        name: internalOwnerId
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SCMUserMappingsResponseDTO'
          description: The response contains:<ul><li>`ownerInternalId` indicates the owner id for which the user mappings were created.</li><li>`inherited` is always `true` if the ownerType is application</li><li>`userMapping` is an object containing `role` and `mappings`.<ul><li> `role` indicates the role assigned to users during automatic role assignment.</li><li>`mappings` contain all existing user mappings from the SCM sytem to IQ.</li></ul></ul>
      tags:
      - Source Control
      summary: Get user mappings by owner
      x-summary-source: derived
  /api/v2/sourceControl/automaticRoleAssignment/{publicId}:
    post:
      description: 'Use this method to automatically grant the supplied role to all contributors of a repository on a given application.


        Prerequisites for automatic role assignment are:


        SCM configuration for the application and authentication token should exist.


        The contributors to the repository should match a user in IQ based on the supplied mappings.


        Either user mapping strategies have been configured for your organization, or they are provided in the request


        Permissions required: Edit access control on the application.'
      operationId: automaticRoleAssignment
      parameters:
      - description: Enter the public applicationId for automatic role assignment.
        in: path
        name: publicId
        required: true
        schema:
          type: string
      requestBody:
        content:
          '*/*':
            schema:
              $ref: '#/components/schemas/SCMUserMappingsDTO'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SCMUserMatchingResultDTO'
          description: 'The ''developer'' role has automatically been assigned to all contributors of the repository, who matched IQ Server users via the provided matching strategies.


            The response contains all usernames that were successfully granted the role provided on the given application as well as an indication of which matching strategy was the first to match a user.'
      tags:
      - Source Control
      summary: Automatic role assignment
      x-summary-source: derived
  /api/v2/sourceControl/{ownerType}/{internalOwnerId}:
    delete:
      description: 'Use this method to delete a SCM setting for the specified ownerType/ownerId.


        Permissions required: Edit IQ Elements'
      operationId: deleteSourceControl
      parameters:
      - description: Enter the value for ownerType.
        in: path
        name: ownerType
        required: true
        schema:
          enum:
          - application
          - organization
          pattern: application|organization
          type: string
      - description: Enter the value for internal ownerId.
        in: path
        name: internalOwnerId
        required: true
        schema:
          type: string
      responses:
        '204':
          description: The SCM setting for the specified ownerType/ownerId has been successfully deleted.
      tags:
      - Source Control
      summary: Delete source control
      x-summary-source: derived
    get:
      description: 'Use this method to retrieve the source control configuration settings for an organization or an application.


        Permissions required: View IQ Elements'
      operationId: getSourceControl_1
      parameters:
      - description: Enter the value for ownerType.
        in: path
        name: ownerType
        required: true
        schema:
          enum:
          - application
          - organization
          pattern: application|organization
          type: string
      - description: Enter the value for internal ownerId. Use ROOT_ORGANIZATION_ID for the root organization
        in: path
        name: internalOwnerId
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiSourceControlDTO'
          description: 'The response contains source control configuration settings for the specified ownerId.


            <ul><li><code>id</code> is the owner internal ID.</li><li><code>repositoryUrl</code> indicates the http(s) and ssh urls for the application specified in the ownerId.</li><li><code>username</code> is retrieved if available on the SCM system, e.g. for Bitbucket Server and Cloud.</li><li><code>provider</code> indicates the name of the SCM system.</li><li><code>baseBranch</code> indicates the name of the last selected branch.</li><li><code>enablePullRequests</code> has been deprecated in version 124.</li><li><code>remediationPullRequestsEnabled</code> indicates if the Automated Pull Requests feature is enabled.</li><li><code>enableStatusChecks</code> has been deprecated in version 124.</li><li><code>statusChecksEnabled</code> is an internal field.</li><li><code>pullRequestCommentingEnabled</code> indicates if the Pull Request Commenting feature is enabled.</li><li><code>sourceControlEvaluationsEnabled</code> indicates if the source control evaluations are enabled for the continuous risk profile feature.</li><li><code>sourceControlScanTarget</code> indicates the path inside the repository.</li><li><code>sshEnabled</code> indicates if ssh is enabled.</li><li><code>commitStatusEnabled</code> indicates if interaction with the commit statuses on the SCM system is enabled.</li></ul>'
      tags:
      - Source Control
      summary: Get source control 1
      x-summary-source: derived
    post:
      description: 'Use this method to create a source control configuration setting.


        Permissions required: Edit IQ Elements'
      operationId: addSourceControl
      parameters:
      - description: Enter the value for ownerType.
        in: path
        name: ownerType
        required: true
        schema:
          enum:
          - application
          - organization
          pattern: application|organization
          type: string
      - description: Enter the value for internal ownerId. Use ROOT_ORGANIZATION_ID for root organization.
        in: path
        name: internalOwnerId
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApiSourceControlDTO'
        description: Specify the SCM settings for the ownerId specified above in the request JSON.<ul><li><code>id</code> is the internal owner ID.</li><li><code>repositoryUrl</code> is the http(s) and ssh urls for the application specified in the ownerId.</li><li><code>username</code> is optional, can be provided for Bitbucket Server and Cloud.</li><li><code>token</code> is optional,if inherited. If provided, this value will override the value inherited from the root organization, organization or application level.<li><code>provider</code> is the name of of the SCM system. Allowed values are <code>azure</code>, <code>github</code>, <code>gitlab</code>, and <code>bitbucket</code>.</li><li><code>baseBranch</code> is required for the root organization. Organizations and applications inherit from the root unless overridden.</li><li><code>enablePullRequests</code> has been deprecated in version 124.</li><li><code>remediationPullRequestsEnabled</code> is optional. Set it to `true` to enable the Automated Pull Requests.</li><li><code>enableStatusChecks</code> has been deprecated in version 124.</li><li><code>statusChecksEnabled</code> is an internal field.</li><li><code>pullRequestCommentingEnabled</code> is optional. Set it to `true` to enable the  Pull Request Commenting feature.</li><li><code>sourceControlEvaluationsEnabled</code> is set to `true` to enable source control evaluations for the continuous risk profile feature.</li><li><code>sourceControlScanTarget</code> is the path inside the repository.</li><li><code>sshEnabled</code> is set to `true` to enable ssh.</li><li><code>commitStatusEnabled</code> is set to `true` if interaction with the commit statuses on the SCM is enabled.</li></ul>
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiSourceControlDTO'
          description: The Source Control Management (SCM) settings have been created successfully.
      tags:
      - Source Control
      summary: Add source control
      x-summary-source: derived
    put:
      description: 'Use this method to update an existing SCM setting.


        Permissions required: Edit IQ Elements'
      operationId: updateSourceControl
      parameters:
      - description: Enter the value for ownerType.
        in: path
        name: ownerType
        required: true
        schema:
          enum:
          - application
          - organization
          pattern: application|organization
          type: string
      - description: Enter the internal ownerId. Use ROOT_ORGANIZATION_ID for the root organization.
        in: path
        name: internalOwnerId
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApiSourceControlDTO'
        description: Specify the SCM settings for the ownerId specified above in the request JSON.<ul><li><code>id</code> is the internal owner ID.</li><li><code>repositoryUrl</code> is the http(s) and ssh urls for the application specified in the ownerId.</li><li><code>username</code> is optional, can be provided for Bitbucket Server and Cloud.</li><li><code>token</code> is optional if inherited. If provided, this value will override the value inherited from the root organization, organization or application level.<li><code>provider</code> is the name of of the SCM system. Allowed values are <code>azure</code>, <code>github</code>, <code>gitlab</code>, and <code>bitbucket</code>.</li><li><code>baseBranch</code> is required for the root organization. Organizations and applications inherit from the root unless overridden.</li><li><code>enablePullRequests</code> has been deprecated in version 124.</li><li><code>remediationPullRequestsEnabled</code> is optional. Set it to `true` to enable the Automated Pull Requests.</li><li><code>enableStatusChecks</code> has been deprecated in version 124.</li><li><code>statusChecksEnabled</code> is an internal field.</li><li><code>pullRequestCommentingEnabled</code> is optional. Set it to `true` to enable the  Pull Request Commenting feature.</li><li><code>sourceControlEvaluationsEnabled</code> is set to `true` to enable source control evaluations for the continuous risk profile feature.</li><li><code>sourceControlScanTarget</code> is the path inside the repository.</li><li><code>sshEnabled</code> is set to `true` to enable ssh.</li><li><code>commitStatusEnabled</code> is set to `true` if interaction with the commit statuses on the SCM is enabled.</li></ul>
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiSourceControlDTO'
          description: The SCM settings have been updated successfully. The JSON returned shows the updated values.
      tags:
      - Source Control
      summary: Update source control
      x-summary-source: derived
  /api/v2/sourceControl/relay/deregister:
    post:
      tags:
      - Source Control
      description: 'Deregister this IQ Server from the SCM webhook relay. Drops the local relay_configuration row and asks the relay to delete the customer record (SQS queue + DynamoDB row). Required before switching auth modes (PAT ↔ GitHub App) since the relay rejects cross-mode switching of an existing customer.


        Permissions required: System Configuration.'
      operationId: deregisterFromRelay
      responses:
        '200':
          description: Deregistration succeeded (or the local row was already absent).
        '412':
          description: The relay integration feature flag is disabled.
      summary: Deregister from relay
      x-summary-source: derived
  /api/v2/sourceControl/githubAppWebhookUrl:
    get:
      tags:
      - Source Control
      description: 'Returns the App-level webhook URL the customer must paste into the GitHub App configuration. Same value for every customer; available before any registration exists because the URL is needed when creating the App.


        Permissions required: Manage Automatic SCM Configuration.'
      operationId: getGitHubAppWebhookUrl
      responses:
        '200':
          description: The webhook URL.
        '404':
          description: The relay base URL is not configured.
        '412':
          description: The relay integration feature flag is disabled.
      summary: Get git hub app webhook url
      x-summary-source: derived
  /api/v2/sourceControl/relayWebhookSecret:
    get:
      tags:
      - Source Control
      description: 'Returns the per-customer HMAC signing secret used to verify webhook deliveries from the SCM provider, when a PAT-mode relay registration exists. GitHub App registrations have no per-customer secret and return 404.


        Permissions required: Manage Automatic SCM Configuration.'
      operationId: getRelayWebhookSecret
      responses:
        '200':
          description: The webhook signing secret.
        '404':
          description: No PAT-mode relay registration exists.
        '412':
          description: The relay integration feature flag is disabled.
      summary: Get relay webhook secret
      x-summary-source: derived
  /api/v2/sourceControl/relayWebhookUrl:
    get:
      tags:
      - Source Control
      description: 'Returns the SCM webhook URL the IQ Server is registered against, when the relay integration is enabled and registered.


        Permissions required: Manage Automatic SCM Configuration.'
      operationId: getRelayWebhookUrl
      responses:
        '200':
          description: The webhook URL.
        '404':
          description: No relay registration exists.
        '412':
          description: The relay integration feature flag is disabled.
      summary: Get relay webhook url
      x-summary-source: derived
  /api/v2/sourceControl/relay/register:
    post:
      tags:
      - Source Control
      description: 'Re-register this IQ Server with the SCM webhook relay. An optional JSON body with installationId and webhookSecret routes the call to the GitHub App registration path; an empty/missing body uses the PAT path.


        Permissions required: System Configuration.'
      operationId: registerWithRelay
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RelayRegisterAdminRequest'
      responses:
        '200':
          description: Registration succeeded.
        '412':
          description: The relay integration feature flag is disabled or relayUrl is not configured.
        '503':
          description: The relay is unavailable.
      summary: Register with relay
      x-summary-source: derived
  /api/v2/sourceControl/relay/rotate-key:
    post:
      tags:
      - Source Control
      description: 'Rotate the IQ→relay API key. The relay generates a fresh key and keeps the previous key valid for a 5-minute grace window so in-flight polls do not fail. The new plaintext is returned exactly once.


        Permissions required: System Configuration.'
      operationId: rotateRelayApiKey
      responses:
        '200':
          description: Rotation succeeded; response body contains the new api key and the ISO-8601 instant at which the previous key stops being accepted.
        '412':
          description: The relay integration feature flag is disabled.
        '503':
          description: The relay is unavailable.
      summary: Rotate relay api key
      x-summary-source: derived
  /api/v2/sourceControl/relay/rotate-webhook-secret:
    post:
      tags:
      - Source Control
      description: 'Rotate the per-customer PAT webhook signing secret. The relay accepts both old and new signatures during a 5-minute grace window so the SCM provider''s webhook configuration can be updated without dropping deliveries. The new plaintext is returned exactly once — paste it into the SCM provider''s webhook secret field.


        Permissions required: System Configuration.'
      operationId: rotateRelayWebhookSecret
      responses:
        '200':
          description: Rotation succeeded; response body contains the new webhook secret and the ISO-8601 instant at which the previous secret stops being accepted.
        '412':
          description: The relay integration feature flag is disabled.
        '503':
          description: The relay is unavailable.
      summary: Rotate relay webhook secret
      x-summary-source: derived
components:
  schemas:
    UserMapping:
      properties:
        from:
          enum:
          - SCM_USERNAME
          - SCM_EMAIL
          - SCM_FULLNAME
          - GITLOG_EMAIL
          - GITLOG_FULLNAME
          type: string
        to:
          enum:
          - IQ_USERNAME
          - IQ_EMAIL
          - IQ_FULLNAME
          type: string
      type: object
    SCMUserMappingsDTO:
      properties:
        mappings:
          items:
            $ref: '#/components/schemas/UserMapping'
          type: array
        role:
          type: string
      type: object
    SCMUserMappingsResponseDTO:
      properties:
        inherited:
          type: boolean
        ownerInternalId:
          type: string
        userMapping:
          $ref: '#/components/schemas/SCMUserMappingsDTO'
      type: object
    ApiSourceControlDTO:
      properties:
        authenticationType:
          type: string
        baseBranch:
          type: string
        closePrAfterDays:
          format: int32
          type: integer
        closePrAfterDaysOpenEnabled:
          type: boolean
        closePrOnFailedChecksEnabled:
          type: boolean
        commitStatusEnabled:
          type: boolean
        enablePullRequests:
          type: boolean
        enableStatusChecks:
          type: boolean
        id:
          type: string
        innerSourceAutomatedUpdatesEnabled:
          type: boolean
        manualPullRequestsEnabled:
          type: boolean
        ownerId:
          type: string
        provider:
          type: string
        pullRequestCommentingEnabled:
          type: boolean
        remediationPullRequestsEnabled:
          type: boolean
        repositoryUrl:
          type: string
        sourceControlEvaluationsEnabled:
          type: boolean
        sourceControlScanTarget:
          type: string
        sshEnabled:
          type: boolean
        statusChecksEnabled:
          type: boolean
        token:
          type: string
        username:
          type: string
      type: object
    SCMUserMatchingResultDTO:
      properties:
        matchedUsers:
          items:
            type: string
          type: array
          uniqueItems: true
        successfulMapping:
          $ref: '#/components/schemas/UserMapping'
      type: object
    RelayRegisterAdminRequest:
      type: object
      properties:
        installationId:
          type: string
        webhookSecret:
          type: string
    ApiSourceControlDTO_2:
      type: object
      properties:
        id:
          type: string
        ownerId:
          type: string
        repositoryUrl:
          type: string
        username:
          type: string
        token:
          type: string
        provider:
          type: string
        authenticationType:
          type: string
        baseBranch:
          type: string
        closePrOnFailedChecksEnabled:
          type: boolean
        closePrAfterDaysOpenEnabled:
          type: boolean
        closePrAfterDays:
          type: integer
          format: int32
        enablePullRequests:
          type: boolean
        remediationPullRequestsEnabled:
          type: boolean
        enableStatusChecks:
          type: boolean
        statusChecksEnabled:
          type: boolean
        pullRequestCommentingEnabled:
          type: boolean
        sourceControlEvaluationsEnabled:
          type: boolean
        sourceControlScanTarget:
          type: string
        sshEnabled:
          type: boolean
        commitStatusEnabled:
          type: boolean
        manualPullRequestsEnabled:
          type: boolean
        innerSourceAutomatedUpdatesEnabled:
          type: boolean
        nonGoldenPullRequestsEnabled:
          type: boolean
  securitySchemes:
    BasicAuth:
      scheme: basic
      type: http
    BearerAuth:
      bearerFormat: JWT
      scheme: bearer
      type: http
x-refined-from:
- sonatype-lifecycle-openapi.yml
- sonatype-iq-openapi.yml