Build API
API to report builds and test results to Ketryx
Last updated
Was this helpful?
API to report builds and test results to Ketryx
Last updated
Was this helpful?
Ketryx exposes an API to report builds and test results programmatically. There is also a formal OpenAPI specification defining this API, and a separate page about authentication and API keys. You can also take a look at the implementation of the Ketryx GitHub Action for how this API can be interacted with.
You should either pass in the version
parameter to associate the build with a particular version, or set the commitSha
parameter so the build will be associated with any version whose release ref pattern (as configured in the Ketryx project settings) resolves to that commit. The version
parameter can be the Ketryx version ID (KXVSN...
) or the full version name (e.g. App v1.0.0
). Either way, automated tests need to be associated with a particular version (not the Current state), so they will not show up in Ketryx test management unless you create a version.
You can combine the reporting of test results with one or more checks (checkDependenciesStatus
, checkReleaseStatus
), or make separate requests. Typically, test results will be reported for all release candidate builds, while the final check for checkReleaseStatus
would happen in the deployment script to production (before actually triggering the deployment).
A particular set of uploaded build artifacts may be detected as required build documents to either block the release of a Ketryx version, or help gathering important build documents for a release in an automated way.
To enable tracking for required build documents on the release / Git commit level, please refer to the relevant Advanced settings section for more details.
Upload a Cucumber JSON build artifact to Ketryx:
with an attached file (e.g., cucumber.json
) as multipart form data. This returns a JSON response of the following form:
Using the id
from the response, make another request to report a build that produced this build artifact:
Ketryx will parse the Cucumber JSON file and create corresponding automatic test executions, based on annotations in the test file as described in MAN-06 Test Management.
As an alternative to uploading Cucumber JSON or JUnit XML files to Ketryx, you can report individual test results directly, using the tests
property:
Each test may optionally reference one or more artifacts
as well.
Upload an SPDX build artifact to Ketryx:
with an attached file (e.g., spdx.json
) as multipart form data. This returns a JSON response of the following form:
Using the id
from the response, make another request to report a build that produced this build artifact:
Ketryx will parse the SPDX JSON file and create corresponding dependencies as defined within these files. It extracts crucial information about software packages, including version, license, and advisory information (introduced in SPDX version 2.3), which pertains to any vulnerabilities associated with the software packages.
Upload a CycloneDX build artifact to Ketryx:
with an attached file (e.g., cyclonedx.json
) as multipart form data. This returns a JSON response of the following form:
Using the id
from the response, make another request to report a build that produced this build artifact:
Ketryx will parse the CycloneDX JSON file and create corresponding dependencies as defined within these files. It extracts crucial information about software packages, including version, license, and vulnerability information, which pertains to any vulnerabilities associated with the software packages.
To check whether all SOUP dependencies in a particular version of a project are controlled:
This returns a JSON response containing an ok
property which will be true
if all dependencies are accepted and fully approved, or false
otherwise. If ok
is false
, the error
property provides more details about what is missing.
To check whether a version has been released in Ketryx (e.g., to block the deployment of an unreleased version to production):
This returns a JSON response containing an ok
property which will be true
if the version has been fully released in Ketryx, or false
otherwise.
Reports a build to Ketryx, potentially including test results. Additionally, certain checks can be performed, namely whether all software dependencies are accepted and controlled, and/or whether the given version(s) are fully released in Ketryx.
The reported build can be associated with a particular version directly (via version
),
or with any versions given a particular commit (via commitSha
), based on the release ref pattern
configured in the Ketryx project.
/builds
Ketryx project ID
KXPRJ49GQYFQ5RR9KRTPWTRTC39YZ9W
Commit SHA associated with this build. Either this or the version
must be set. If the given commit is associated with multiple versions in Ketryx (via the release ref pattern configured for the Ketryx project), the status of all those matching versions will be considered.
ad4db8ac1e70bd41aa8bcee6f00a3a1e36bb0e01
Build name. For each unique name, the latest build is part of the set of effective builds for a project. Empty by default.
ci-e2e-batch1
Log output to store for this build
Source URL associated with this build. This is used for documentation purposes and to link back to the build from the Ketryx interface.
https://github.com/Ketryx/ketryx/actions/runs/4991785273
Whether to update the associated repositories (specified in repositoryUrls
) synchronously before returning from this API. This is useful when checking for the status of dependencies (using checkDependenciesStatus
), to ensure that Ketryx has up-to-date data from the repository before performing the check.
Whether to perform a check of dependencies in the associated commit(s). If not all dependencies are accepted and in a controlled state
Whether to perform a check of the overall release of the associated version(s).
This is important to find the relevant commits for a given version
, and to trigger updates of the repositories before checking the build status. The URLs should match the repository URLs as configured in the Ketryx project settings.
["https://github.com/Ketryx/ketryx"]
Ketryx version ID or the full version name. Either this or the commitSha
must be set.
Build artifacts associated with the overall build, referencing files uploaded via the /build-artifacts
API
Uploads a build artifact to Ketryx, which can then be included in a build using the /builds
API. The file is encoded in a request of type multipart/form-data
.
/build-artifacts
Ketryx ID of the project to upload the file to
KXPRJ49GQYFQ5RR9KRTPWTRTC39YZ9W