Skip to main content

External CI Example

In this example, we will show how you should send the events to the CodeNOW API to integrate your external CI pipeline with CodeNOW.

Prerequisites​

Example​

Suppose we have a component with ID my-component-id (ID is the Technical Name in the detail of the component). We want to inform CodeNOW about the execution of an external CI pipeline. To do this, we need to send a series of events to the CodeNOW API as described in CI Events. The following example demonstrates the bare minimum of events that need to be sent to CodeNOW for a successful deployment.

For the example, we will be using curl CLI.

info

The pipelineId is a unique identifier of the pipeline run. The whole series of events must share the same pipelineId. For the sake of this example, we will use a placeholder value my-pipeline-id.

info

Not all of the fields are required, to learn more, visit the API documentation.

Start event​

Each execution of an external CI pipeline has to start with a start event. By sending codenow.ci.start.event you indicate the execution of the pipeline.

Example request:

curl -L -X POST 'https://api.cloud.codenow.com/ci/webhook' \
         --header 'Accept: application/vnd.codenow.v1+json' \
         --header 'Content-Type: application/vnd.codenow.v1+json' \
         --header 'X-Codenow-Api-Key: {YOUR_CI_KEY}' \
         --data-raw '{
             "type": "codenow.ci.start.event",
             "version": "application/vnd.codenow.v1+json",
             "pipelineId": "my-pipeline-id",
             "componentId": "my-component-id",
             "buildVersion": "0.0.1",
             "createdAt": "2024-01-01T00:00:00.000Z",
             "actor": {
                 "username": "johnsmith",
                 "fullname": "John Smith"
             },
             "pipelineName": "My Pipeline",
             "dashboardUrl": "https://my-dashboard.com"
         }'

After sending the event, you should be able to see a new build in the component detail:

Start event

Result event​

Once CodeNOW receives the start event, you can start sending the results of the pipeline steps using the codenow.ci.result.event.

info

Depending on which approach is better for you, you can either send the results in one event like in the example, or you can send multiple events with payload representing the currently finished step of the pipeline.

tip

You can also use the link result subtype to add results that contain a URL. The URL leads to the build result that your pipeline produced.

Example request:

curl -L -X POST 'https://api.cloud.codenow.com/ci/webhook' \
         --header 'Accept: application/vnd.codenow.v1+json' \
         --header 'Content-Type: application/vnd.codenow.v1+json' \
         --header 'X-Codenow-Api-Key: {YOUR_CI_KEY}' \
         --data-raw '{
             "type": "codenow.ci.result.event",
             "version": "application/vnd.codenow.v1+json",
             "pipelineId": "my-pipeline-id",
             "createdAt": "2024-01-01T00:00:00.000Z",
             "payload": [{
                 "type": "git-revision",
                 "version": "v1",
                 "repositoryUrl": "url-to-the-repository",
                 "branch": "branch-name",
                 "commitSha": "hash-of-the-commit"
             },
             {
                 "type": "code-quality",
                 "version": "v1",
                 "system": "SonarQube",
                 "url": "url-to-the-sonarqube-report",
             },
             {
                 "type": "container",
                 "version": "v1",
                 "repositoryUrl": "url-to-the-container-repository",
                 "artifactPath": "path-to-the-container-artifact",
                 "artifactVersion": "0.0.1"
             },
             {
                 "type": "git-tag",
                 "version": "v1",
                 "tag": "tag-name"
             },
             {
                 "type": "helm",
                 "version": "v1",
                 "repositoryUrl": "url-to-the-artifact-repository",
                 "artifactPath": "path-to-the-artifact",
                 "artifactVersion": "0.0.1"
             }],
         }'

After sending the event, you should be able to see the results of the steps in the pipeline in the build detail:

Result event

End event​

To finish the pipeline execution, you need to send the end event. Send codenow.ci.end.event to report the result of the whole pipeline.

Example request:

curl -L -X POST 'https://api.cloud.codenow.com/ci/webhook' \
         --header 'Accept: application/vnd.codenow.v1+json' \
         --header 'Content-Type: application/vnd.codenow.v1+json' \
         --header 'X-Codenow-Api-Key: {YOUR_CI_KEY}' \
         --data-raw '{
             "type": "codenow.ci.end.event",
             "version": "application/vnd.codenow.v1+json",
             "pipelineId": "my-pipeline-id",
             "createdAt": "2024-01-01T00:00:00.000Z",
             "result": "SUCCESSFUL" // SUCCESSFUL | FAILED | CANCELED
         }'

After sending the event, your pipeline run is finished and you should be able to see the result of the pipeline run in the build history:

End event

What's next?​