Jobs YAML Reference#

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

An example#

This reference page will begin 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
  name: Deploy
  id: 33cbe5af-fafb-424b-b06f-12006929cb08
  create_time: "1539327331"
  update_time: "1539327332"
  start_time: "1539327334"
  finish_time: "1539327340"
      type: e1-standard-2
      os_image: ubuntu1804
  files: []
    value: f7da446084515d25db52b4fe6146db6e81ded482
    value: master
    value: 0137eba3-fb19-41f8-87ac-77e040d437f6
    value: b6452489-3bd7-4a09-a73d-a834b6cad1ac
    value: b6452489-3bd7-4a09-a73d-a834b6cad1ac
    value: b6452489-3bd7-4a09-a73d-a834b6cad1ac
  - name: docker-secrets
  - checkout
  - gem install redcarpet
  - if [ $SEMAPHORE_GIT_BRANCH == "master" ]; then ./deploy_docs.rb; fi
  project_id: 0dd982e8-32f5-4037-983e-4de01ac7fb1e
  state: FINISHED
  result: PASSED
    - name: ssh
      number: 57693

So, the description of a job as returned by Semaphore 2.0 contains many properties. Some of them are defined by Semaphore 2.0 whereas other can be defined by the user. You can visit the sem command line tool Reference page for learning how to define a job using the sem create command.



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.

The list of values for apiVersion: v1alpha.


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

The list of values for kind: Job.


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.


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

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


The value of the id property is automatically generated and assigned by Semaphore 2.0 and is unique among all jobs. It should not be edited.


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 of the job.


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 the job was altered.


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 the job started to execute.


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 the job finished its execution.


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


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

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

You can learn more about the agent property and the properties under it at the Pipeline YAML Reference page.


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


The type property is intended for specifying the machine (hardware) you would 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 page.


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

The list of values for os_image: ubuntu1804.


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


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

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


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


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


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

This property can be modified only by Semaphore 2.0.


The state property holds the state of the job.

The list of values for state: PENDING, QUEUED, RUNNING and FINISHED.

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


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

The list of values for result: NONE, PASSED, FAILED and STOPPED.

  • NONE: the jobs 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 finishing.

agent status#

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


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.


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.

See also#