CI Configuration REST API

CI Configuration REST API

Overview

Use this REST API to centrally manage CI evaluation settings in the Lifecycle organization and application hierarchy. This can simplify CI onboarding, especially for customers with many pipelines and consistent project structures.

The API lets you add, update, and remove CI configuration at any node in the organization hierarchy. The same configuration model applies to all supported CI integrations and Sonatype IQ CLI.

Parameters that stay with the pipeline or CLI

Some CI parameters, such as the IQ Server URL and credentials, application ID, and evaluation stage, must stay with the pipeline or CLI invocation. Most other supported CI parameters can be managed through the IQ organization or application hierarchy.

Parameter priority

Before running the evaluation step, the integration or CLI builds a parameter set by combining API-stored configuration with pipeline-provided parameters. The resulting parameter set is used at runtime.

  1. The CI integration starts with a base parameter set containing the IQ Server URL and credentials, application ID, and evaluation stage from the pipeline. All other parameter values are set to their default values.

  2. The integration reads the API-stored configuration based on the application ID.

  3. If configuration exists, it is used to update the base parameter set.

  4. If parameterPriority equals API, the current parameter set becomes the final parameter set and all remaining pipeline parameters are ignored.

  5. If parameterPriority equals CI or is not specified, all pipeline parameters with non-empty values override the values in the updated parameter set, resulting in the final parameter set.

  6. If no API data is retrieved, the pipeline-provided parameters become the final parameter set.

This approach works well for both new customers setting up pipelines and existing customers moving to a more centralized configuration.

At the start of the evaluation step, CI integrations log the effective parameters, their values, and whether the values came from the API or the CI environment, which helps with troubleshooting.

Configuration format

The API uses a hierarchical JSON format for both storage and communication. This format makes it easy to add more parameters in the future with minimal changes.

{
  "parameterPriority": "CI", // options: API, CI
  "scanPatterns": [\
    "pattern.one",\
    "pattern.two"\
  ], // Ant-style patterns
  "moduleExcludes": [\
    "module.one",\
    "module.two"\
  ], // Ant-style patterns
  "enableDebugLogging": false, // true or false
  "failBuildOnNetworkError": true, // true or false
  "failBuildOnScanningErrors": true, // true or false
  "failBuildOnPolicyWarnings": false, // true or false
  "unstableBuildOnPolicyWarnings": true, // true or false
  "advancedProperties": [\
    "key1=value1",\
    "key2=value2"\
  ],
  "resultFile": "result.json",
  "sarifFile": "sarif.json",
  "download": {
    "iqCliVersion": "2.1.0-01",
    "iqCliUrl": "https://your.site.com/nexus-iq-cli-2.7.0-01.jar"
  }, // for integrations relying on IQ CLI for evaluations
  "reachability": {
    "javaAnalysis": {
      "enabled": true, // true or false
      "entrypointStrategy": "CONCRETE",
      "namespaces": [\
        "namespace.one",\
        "namespace.two"\
      ]
    },
    "javaScriptAnalysis": {
      "enabled": true, // true or false
      "jsSources": [\
        "pattern.one",\
        "pattern.two"\
      ], // Ant-style patterns
      "jsExcludes": [\
        "pattern.one",\
        "pattern.two"\
      ], // Ant-style patterns
      "projectRoot": ".", // project root folder
      "nodeJsExecutable": "/path/to/node" // full Node.js path
    },
    "failOnError": false // true or false
  }
}

All parameters are optional, so any or all of them can be omitted. Even {} is a valid configuration, although not a useful one.

REST API

Get CI configuration

GET /api/v2/config/ci/{ownerType}/{ownerId}?direct=[true|false]

Requires the View IQ elements permission in IQ.

The response is similar to the configuration format shown above, but enhanced with provenance information, or HTTP 404 if no records are found. For example:

{
  "data": {
    "parameterPriority": "CI",
    "scanPatterns": [\
      "pattern.one",\
      "pattern.two"\
    ],
    "moduleExcludes": [\
      "module.one",\
      "module.two"\
    ],
    "enableDebugLogging": false,
    "failBuildOnNetworkError": true,
    "..."
  },
  "source": {
    "parameterPriority": "ROOT_ORG",
    "scanPatterns": "ROOT_ORG",
    "moduleExcludes": "72a2b2287331489a927848259609334d",
    "enableDebugLogging": "test-application-01",
    "failBuildOnNetworkError": "ROOT_ORG",
    "..."
  }
}

Update CI configuration

PUT /api/v2/config/ci/{ownerType}/{ownerId}

Requires the Edit IQ elements permission in IQ.

Payload: JSON content as defined in the Configuration format section above. The payload is stored as provided.

Returns HTTP 200 if successful.

Delete CI configuration

DELETE /api/v2/config/ci/{ownerType}/{ownerId}

Requires the Edit IQ elements permission in IQ.

Returns HTTP 204 if successful.

Example: merged records

Assume the following organization hierarchy branch exists in Lifecycle: ROOT_ORG > test-org > test-app.

A Lifecycle user adds the following CI parameters to the root organization:

PUT {{host}}/api/v2/config/ci/organization/{{ROOT_ORGANIZATION_ID}}
Accept: application/json
Authorization: Basic {{username}} {{password}}
Content-Type: application/json

{
  "parameterPriority": "CI",
  "failBuildOnScanningErrors": true
}

Then the user adds more CI configuration to test-org. Notice that failBuildOnScanningErrors is specified again with a different value:

PUT {{host}}/api/v2/config/ci/organization/{{test-org-id}}
Accept: application/json
Authorization: Basic {{username}} {{password}}
Content-Type: application/json

{
  "scanPatterns": [\
    "*.xml"\
  ],
  "failBuildOnScanningErrors": false
}

Finally, more CI parameters are added to test-app:

PUT {{host}}/api/v2/config/ci/application/{{test-app-id}}
Accept: application/json
Authorization: Basic {{username}} {{password}}
Content-Type: application/json

{
  "failBuildOnPolicyWarnings": false,
  "advancedProperties": [\
    "apiProp=apiVal"\
  ]
}

The following merged record is returned when checking the CI configuration for the test-app node:

GET {{host}}/api/v2/config/ci/application/{{test-app-id}}

{
  "data": {
    "parameterPriority": "CI",
    "scanPatterns": [\
      "*.xml"\
    ],
    "failBuildOnScanningErrors": false,
    "failBuildOnPolicyWarnings": false,
    "advancedProperties": [\
      "apiProp=apiVal"\
    ]
  },
  "source": {
    "parameterPriority": "ROOT_ORGANIZATION_ID",
    "advancedProperties": "test-app",
    "scanPatterns": "{{test-org-id}}",
    "failBuildOnScanningErrors": "{{test-org-id}}",
    "failBuildOnPolicyWarnings": "test-app"
  }
}

All double bracket elements above, for example {{host}} or {{test-app-id}}, are replaced with actual values in practice.

Parameter Logging in CI Integrations Example

This is how the preceding setup would be logged by a CI integration at the start of the evaluation step:

-----------------------------------------------------------------------------  
Parameter Configuration   (with sources):  
   Parameter priority: CI   (API - org: Root Organization)  
   IQ Server URL: https://int-test.sonatype.app   (CI)  
   IQ Server credentials: ***:***   (CI)  
   IQ Server stage: build   (CI)  
   IQ Server application: test-app   (CI)  
   Scan patterns: [ *.xml ]   (API - org: Test Org)  
   Fail build on scanning errors: false   (API - org: Test Org)  
   Fail build on policy warnings: false   (API - app: test-app)  
   Advanced properties: [ apiProp=apiVal ]   (API - app: test-app)  
-----------------------------------------------------------------------------

The parameters listed above are the effective parameters that will be used for the evaluation step.