Jobs YAML Reference#

This document is the reference to the YAML grammar used for managing Semaphore 2.0 jobs.

An example#

Let's start with an YAML example as returned by the sem get jobs [JOB ID] command:

$ sem get jobs 33cbe5af-fafb-424b-b06f-12006929cb08
apiVersion: v1alpha
kind: Job
metadata:
  name: Deploy
  id: 33cbe5af-fafb-424b-b06f-12006929cb08
  create_time: "1539327331"
  update_time: "1539327332"
  start_time: "1539327334"
  finish_time: "1539327340"
spec:
  agent:
    machine:
      type: e1-standard-2
      os_image: ubuntu2004
  files: []
  envvars:
  - name: SEMAPHORE_GIT_SHA
    value: f7da446084515d25db52b4fe6146db6e81ded482
  - name: SEMAPHORE_GIT_BRANCH
    value: master
  - name: SEMAPHORE_WORKFLOW_ID
    value: 0137eba3-fb19-41f8-87ac-77e040d437f6
  - name: SEMAPHORE_PIPELINE_ARTEFACT_ID
    value: b6452489-3bd7-4a09-a73d-a834b6cad1ac
  - name: SEMAPHORE_PIPELINE_ID
    value: b6452489-3bd7-4a09-a73d-a834b6cad1ac
  - name: SEMAPHORE_PIPELINE_0_ARTEFACT_ID
    value: b6452489-3bd7-4a09-a73d-a834b6cad1ac
  secrets:
  - name: docker-secrets
  commands:
  - checkout
  - gem install redcarpet
  - if [ $SEMAPHORE_GIT_BRANCH == "master" ]; then ./deploy_docs.rb; fi
  project_id: 0dd982e8-32f5-4037-983e-4de01ac7fb1e
status:
  state: FINISHED
  result: PASSED
  agent:
    ip: 94.130.207.151
    ports:
    - name: ssh
      number: 57693

As you can see, the description of a job as returned by Semaphore 2.0 contains many properties. Some of them are defined by Semaphore 2.0, whereas others can be defined by the user. You can visit the sem command line tool Reference documentation to learn how to define a job using the sem create command.

Properties#

apiVersion#

The apiVersion property defines the version of the YAML grammar that will be used in the current YAML file. Different versions might have different features.

Here is a list of values for the apiVersion property: v1alpha.

kind#

The kind property defines the purpose of a YAML file. For a YAML file that will be used for defining jobs, the value of the kind property should be Job.

Here is a list of values for the kind property: Job.

metadata#

The metadata property defines the metadata of the Jobs YAML file and supports the name, id, create_time, update_time, start_time and finish_time properties.

Currently, only the name property can be defined by the user when creating a new job but this might change in future versions.

name#

The value of the name property, which is a string in the metadata context, defines the name of a job.

As each job is uniquely identified by its Job ID, multiple jobs can share the same job name without conflicts.

id#

The value of the id property is automatically generated and assigned by Semaphore 2.0 and is unique to each job. It should not be edited.

create_time#

The value of the create_time property is automatically generated by Semaphore 2.0 and is in the UNIX epoch format. It holds the time of creation for a job.

update_time#

The value of the update_time property is automatically generated by Semaphore 2.0 and is in the UNIX epoch format. It holds the last time a job was altered.

start_time#

The value of the start_time property is automatically generated by Semaphore 2.0 and is in the UNIX epoch format. It holds the time that a job started its execution.

finish_time#

The value of the finish_time property is automatically generated by Semaphore 2.0 and is in the UNIX epoch format. It holds the time that a job finished its execution.

spec#

The spec property holds a list of properties that hold the full specification of a job.

agent#

The agent property holds one additional property named machine that identifies the environment, i.e. the hardware and Operating System of the Virtual Machine in which a job will be executed.

If you are creating a new job, you can define the values of type and os_image as you wish, provided that you use valid values.

You can learn more about the agent property and the properties associated with it in the Pipeline YAML Reference documentation.

machine#

The machine property, which can only be defined under agent, requires two properties named type and os_image.

type#

The type property is intended for specifying the machine (hardware) you want to use on the Virtual Machine for building a specific job.

You can learn about the list of valid values for the type property by visiting the Machine Types documentation.

os_image#

The os_image property specifies the operating system and the version of the operating system that will be used on a Virtual Machine.

Here is a list of values for the os_image property: ubuntu2004.

files#

The files property holds a list of file items used for the job. Each file is represented by a path and content pair.

env_vars#

The envvars property holds a list of name and value pairs that represent environment variables.

The name property defines the name of an environment variable. The value property defines the value of an environment variable.

secrets#

The secrets property holds a list with the secrets that will be imported for this job.

commands#

The commands property holds the commands of the job. As a result, the value of the commands property is a list of strings, which represent commands for that job.

status#

The status property is defined by Semaphore 2.0 and describes the current status of a job; it also holds three other properties: state, result, and agent.

This property can only be modified by Semaphore 2.0.

state#

The state property holds the state of a job.

Here is a list of values for the state property: PENDING, QUEUED, RUNNING, and FINISHED.

  • PENDING: the job has been accepted by the Semaphore 2.0 system.
  • QUEUED: the job is waiting for available capacity.
  • RUNNING: the job is processing commands.
  • FINISHED: job processing has finished and the result has been calculated.

result#

The result property holds the result of a job. If the job is running then the value of result will be "".

Here is a list of values for the result property: NONE, PASSED, FAILED, and STOPPED.

  • NONE: the job has not yet finished.
  • PASSED: the job has successfully finished.
  • FAILED: the job has failed, either because a command has failed or because one or more dependancies were not available.
  • STOPPED: the job was terminated before completion.

agent status#

The agent property holds three other properties, named ip, name and ports, that specify the IP address, name and the TCP port number used by the agent running the job.

ip#

The value of the ip property is the IP address of the Virtual Machine used for executing the job. This value is provided by Semaphore 2.0 and should not be changed.

For self-hosted jobs, this value is empty.

name#

The value of the name property is the name used by the agent that was assigned to the job. For cloud jobs, the value of this property is empty. For self-hosted jobs, the value of this property is the name of the self-hosted agent that was assigned to the job.

ports#

The ports property holds a name and number pair. The value of the name property is the protocol used, which is ssh, and the value of the number property is the TCP port number used for the ssh connection.

For self-hosted jobs, this is an empty list.

See also#