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

Before you begin: You need to collect the following:

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:

Copy

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

Before you begin: You need to collect the following:

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:

Copy

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 PUT "$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 be null.
- onError: The script that runs if the job errors. May be null.
config:
- sharedHardware: Whether to use shared hardware configured via Continuous Delivery’s root console, as opposed to workspace-specific hardware. If this is set to true, a custom vmImage cannot be used and useDefaultImage must be set to true.
- 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 be null.
- 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 to docker/podman run, for example “--debug --network=host”. May be null, should not be set if you are not using a container for this job.
- useDefaultImage: Set to false 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 be null if useDefaultImage or sharedHardware are true, and must have a value if useDefaultImage is false.