Add API endpoint for setting the status of external jobs
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
Edited by Tiger Watson