--- title: "Report a build to Ketryx" method: POST path: "/builds" tags: ["Builds"] --- # Report a build to Ketryx `POST /builds` ## Request - Base URL: `https://app.ketryx.com/api/v1` - URL: `https://app.ketryx.com/api/v1/builds` - Auth: HTTP bearer - TypeScript: (a function with typed inputs; its response is checked against the schema) 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. ## Request body - object - `project` string, required: Ketryx project ID - `version` string: Ketryx version ID or the full version name. Either this or the `commitSha` must be set. - `commitSha` string: 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. - `changeRequestNumber` integer: Number of the change request (e.g. GitHub pull request number) to associate with this build. If the change request is not known to Ketryx yet, it is synchronized from the connected repository before checking. - `buildName` string: Build name. For each unique name, the latest build is part of the set of _effective_ builds for a project. Empty by default. - `log` string: Log output to store for this build - `sourceUrl` string: Source URL associated with this build. This is used for documentation purposes and to link back to the build from the Ketryx interface. - `repositoryUrls` string[]: 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. - `syncRepositoryUpdate` boolean: 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. - `tests` object[] - `testedItem` string: Ketryx ID or Jira issue key of the item tested by this test (required). Usually, this will reference a Test Case; but it can also reference a Requirement, Software Item Spec, Anomaly, Change Request, or CAPA directly. - `result` 'PASS' | 'FAIL': Result of the test (required) - `title` string: Title of the test (required) - `log` string: Log text to store with the test - `artifacts` object[]: Build artifacts associated with this particular test, referencing files uploaded via the `/build-artifacts` API - `id` string: Artifact ID, as returned by the `/build-artifacts` API (required) - `artifacts` object[]: Build artifacts associated with the overall build, referencing files uploaded via the `/build-artifacts` API - `id` string: Artifact ID, as returned by the `/build-artifacts` API (required) - `type` 'artifact' | 'cucumber-json' | 'cyclonedx-json' | 'junit-xml' | 'spdx-json': Type of the artifact. The value `artifact` represents a generic file, while other values (`cucumber-json`, `junit-xml`) represent test results that are read by Ketryx according to their respective format. The values `cyclonedx-json` and `spdx-json` represent SBOM files. - `checkDependenciesStatus` boolean: Whether to perform a check of dependencies in the associated commit(s). If not all dependencies are accepted and in a controlled state - `checkChangeRequestItemAssociation` boolean: Whether to fail the build if there is no change request associated with the build (via `changeRequestNumber`), or the change request has no associated items (i.e. no item references in its title or description). - `checkReleaseStatus` boolean: Whether to perform a check of the overall release of the associated version(s). ## Response `200` OK - object - `ok` boolean, required: Whether the build was reported successfully and all checks passed - `error` string: Human-readable error message in case there was an error reporting the build or running any checks. See `errors` for machine-readable error codes. - `errors` object[]: Structured errors encountered while reporting the build or running any checks. Only present when such an error occurred. - `code` string, required: Machine-readable error code. Current codes are `GITHUB_AUTH_FAILED` (the connected repository rejected the stored credentials while syncing the change request) and `CHANGE_REQUEST_SYNC_FAILED` (the change request could not be synced from the connected repository). Additional codes may be added over time. - `message` string, required: Human-readable error message - `buildId` string: Ketryx ID of the reported build - `projectId` string: Ketryx ID of the relevant project - `repositoryIds` string[]: Ketryx IDs of the associated repositories - `versionIds` string[]: Ketryx IDs of the associated project versions - `commitShas` string[]: SHAs of the associated commits - `dependenciesAccepted` boolean: Whether all dependencies have been accepted (if `checkDependenciesStatus` is active) - `dependenciesControlled` boolean: Whether all dependencies are in a controlled state (if `checkDependenciesStatus` is active) - `validationWarnings` object[]: Validation warnings from SBOM processing. Only present when warnings were detected during parsing of SBOM artifacts (CycloneDX or SPDX). - `type` 'INVALID_CPE' | 'INVALID_PURL' | 'GENERIC_CPE' | 'GENERIC_PURL' | 'UNSUPPORTED_CPE' | 'INVALID_CYCLONEDX' | 'INVALID_SPDX': Type of validation warning - `message` string: Human-readable description of the warning - `componentRef` string: Component identifier (bomRef for CycloneDX, SPDXID for SPDX, or component name as fallback) - `componentName` string: Human-friendly component name - `affectedValue` string: The value that triggered the warning (e.g., the invalid CPE/PURL string) ## Other responses - `400`: The request is not valid. - `401`: The requester is not authenticated. - `403`: The requester is unauthorized. - `404`: The resource was not found. --- [API](https://skmtc.dev/ketryx/apis/ketryx-api.md) - [All operations](https://skmtc.dev/ketryx/apis/ketryx-api/llms.txt) - [OpenAPI document](https://skmtc.dev/ketryx/apis/ketryx-api/revisions/a2a484dc35ca?raw)