Add API endpoint for setting the status of external jobs

Everyone can contribute. Help move this issue forward while earning points, leveling up and collecting rewards.

• Close this issue

Proposal

Create an API endpoint that can set the status of an external CI job. Once an external CI job has been started, it will wait until it receives a status via the API (or it times out and fails).

There are two ways of specifying which job to update:

• Using the pipeline ID and the name of the job. A job name must be unique within a pipeline, so providing a pipeline ID and name will only ever refer to one (or zero) jobs.
• Using the ref and sha of the pipeline, and the name of the job. As there can be multiple pipelines running for a single ref/sha combination, multiple jobs may be updated via a single API call (though as above, at most one per pipeline).

If a job is specified that is either not set as external, or is not currently in the waiting_for_callback state, the API call does nothing.

There are two possible outcomes for an external job, success and failed. Both outcomes behave in the same way as they do for traditional CI jobs: if the job is successful, the pipeline continues to the next job. If the job is unsuccessful, the pipeline halts and is marked as failed.

API details

POST /api/v4/projects/:id/pipeline_callback

Attribute	Type	Required	Description
id	integer/string	yes	The ID or URL-encoded path of the project
job_name	string	yes	The name of the external job
job_status	string	yes	The outcome of the external job, either success or failed
ref	string	no(*)	The ref of the pipeline
sha	string	no(*)	The sha of the pipeline
pipeline_id	string	no(*)	The ID of the pipeline

* One of sha + ref and pipeline ID must be specified

Definition of done

• pipeline_callback API endpoint is created
• Jobs in the waiting_for_callback state can be marked as success or failure using a pipeline ID
• Jobs in the waiting_for_callback state can be marked as success or failure using a pipeline ref + sha