Create and update job templates
Use the Continuous Delivery API to create or update custom job templates.
Creating a new job template using the API
Your auth token
The ID of the workspace where you want to use the job template in pipelines. If you need it in multiple workspaces, you need to call this API for each workspace.
Example call:
data="$(cat <<EOF
{
"name": "custom job",
"description": "an example custom job",
"manifest": {
"build": "echo 'hello $FIRST_NAME $LAST_NAME'",
"onSuccess": null,
"onError": "echo 'uh oh'"
},
"config": {
"sharedHardware": false,
"buildCapabilities": ["containerized"],
"buildVars": “FIRST_NAME=Jane\nLAST_NAME=Doe”,
"vmArgs": null,
"vmImage": "puppet/puppet-dev-tools:puppet8",
"useDefaultImage": false
}
}
EOF
)"
type_header='Content-Type: application/json'
auth_header="Authorization: <AUTHORIZATION TOKEN>"
uri="https://<cd4pe host>/cd4pe/api/v2/jobs/templates?workspaceId=<WORKSPACE ID>"
curl --insecure --header "$type_header" --header "$auth_header" --request POST "$uri" --data "$data"
Updating an existing job template using the API
Your auth token
The ID of the workspace where you want to use the job template in pipelines. If you need it in multiple workspaces, you need to call this API for each workspace.
The ID of the job you want to edit.
Important notes:
- All of the top-level fields are optional; any field you supply is updated in the targeted template, and the others are left as-is.
- All fields of the “manifest” and “config” objects are required, and the object replaces the object in the target template wholesale (i.e., no merging occurs).
- If the supplied template ID in the URL does not exist, the request returns a 404. It does not create a new template. Please use the POST request for creating new templates.
Example call:
data="$(cat <<EOF
{
"name": "custom job",
"description": "an example custom job",
"manifest": {
"build": "echo 'hello $FIRST_NAME $LAST_NAME'",
"onSuccess": null,
"onError": "echo 'uh oh'"
},
"config": {
"sharedHardware": false,
"buildCapabilities": ["containerized"],
"buildVars": “FIRST_NAME=Jane\nLAST_NAME=Doe”,
"vmArgs": null,
"vmImage": "puppet/puppet-dev-tools:puppet8",
"useDefaultImage": false
}
}
EOF
)"
type_header='Content-Type: application/json'
auth_header="Authorization: <AUTHORIZATION TOKEN>"
uri="https://<cd4pe host>/cd4pe/api/v2/jobs/templates/<EXISTING JOB ID>?workspaceId=<WORKSPACE ID>"
curl --insecure --header "$type_header" --header "$auth_header" --request POST "$uri" --data "$data"
Field definitions
-
name
: Name of the job. -
description
: Description of the job. -
manifest
:-
build
: The main job script to be run, inside the container if one is specified. -
onSuccess
: The script that runs if the job completes successfully. May benull
. -
onError
: The script that runs if the job errors. May benull
.
-
config
:sharedHardware
: Whether to use shared hardware configured via Continuous Delivery’s root console, as opposed to workspace-specific hardware. If this is set totrue
, a customvmImage
cannot be used anduseDefaultImage
must be set totrue
.buildCapabilities
: A list of the capabilities that the hardware that runs this job is required to have. If you want the job to run in a container, specify“containerized”
here.buildVars
: A string of environment variables that are passed to the image, separated by new lines (“\n”
). These are accessible from your scripts. May benull
.vmArgs
: Arguments to pass to the command that is running the container (either Docker or Podman). A single string with arguments separated by spaces, passed directly todocker/podman run
, for example“--debug --network=host”
. May benull
, should not be set if you are not using a container for this job.useDefaultImage
: Set tofalse
to use a custom image.vmImage
: A custom container image reference to use to run this job. This can be an image from an internal repo, assuming the job hardware has access to it or the image has been preloaded into the container runtime on the host. Must benull
ifuseDefaultImage
orsharedHardware
aretrue
, and must have a value ifuseDefaultImage
isfalse
.