Jobs YAML Reference

Overview

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
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: ubuntu1804
  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

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.

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.

The list of values for apiVersion: v1alpha.

kind

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.

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 the 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 among all jobs. 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 of the 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 the 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 the job started to execute.

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 the 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, 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.

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 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.

os_image

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.

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 the environment variable. The value property defines the value of the 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 are the commands of the job.

status

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.

state

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.

result

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.

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.

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.

See also

Still need help? Contact Us Contact Us