Deployment Targets YAML Reference#

The Deployment Targets YAML reference explains the YAML grammar used for configuring deployment targets. These targets enable the enforcement of strict conditions for triggering pipeline promotions. Those conditions allow you to restrict who (person or a role) can trigger a promotion and on which git reference (branch, tag, and/or pull request).

By integrating promotions with Deployment Targets, you can establish secure Continuous Deployment pipelines that seamlessly align with your current setup.

A deployment target is created within a project and exclusively employed within that project for multiple promotions.



The apiVersion property indicates the version of the YAML grammar employed within the current YAML file. Different versions may introduce varying features.

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


The kind property specifies the purpose of a YAML file. For YAML files intended to define deployment targets, the value of the kind property should be DeploymentTarget.

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


The metadata property defines the metadata for a Deployment Target YAML file, supporting the following properties: id, name, project_id, organization_id, created_by, created_at, updated_by, updated_at, description and url properties.


The id property is an automatically generated unique identifier assigned by Semaphore 2.0 to each deployment target. It should not be modified.


The name property is a string that represents the name of the deployment target. This name is displayed when executing the sem get dt -p [project-name] command. The name should only consist of alphanumerical characters, dashes, underscores, and dots.


The project_id property corresponds to the UUID (Universally Unique Identifier) of the project associated with the deployment target. It should not be modified.


The organization_id property represents the UUID of the organization linked to the deployment target. It should not be modified.


The created_by property contains the UUID of the user who created the deployment target. It should not be modified.


The created_at property indicates the UTC when the deployment target was created. It should not be modified.


The updated_by property stores the UUID of the user who last updated the deployment target. It should not be modified.


The updated_at property denotes the UTC when the deployment target was last updated. It should not be modified.


The description property is a string that describes the deployment target.


The url property is a string containing the URL associated with the deployment target.


The spec property contains a list of deployment target properties.


The state property indicates the state of the deployment target, which can be one of the following values: SYNCING, USABLE, UNUSABLE, or CORDONED. It should not be modified.


The state_message property provides an additional message associated with the deployment target's state. It should not be modified.


The subject_rules property holds a list of subject rules that determine who can trigger promotions when the deployment target is associated with them. Each rule must include the type. Depending on the rule type, the subject_id or git_login may also be required.


The type property of a subject rule can have one of the following values: ANY, USER, ROLE, or AUTO. Each value has a specific meaning:

  • ANY: This rule allows any user to trigger the promotion. There are no restrictions on who can initiate the promotion process.

  • USER: This rule restricts the promotion to specified users who must be assigned to the project. Only these users have the authority to trigger a promotion.

  • ROLE: This rule limits the promotion to specific user roles defined within the project. Only users assigned to these roles can trigger a promotion.

  • AUTO: This rule configures the behavior of auto-promotions for the deployment target. If this rule is not present, auto-promotions will not start even if all the conditions are met.

Please note that these values determine the authorization requirements for triggering promotions based on the subject rule. Choose the appropriate type value based on your desired promotion workflow and access control needs.


The subject_id property is required for USER and ROLE rule types. For USER, the subject_id contains the UUID of the user. If the rule type is ROLE, it should be the name of the project role (e.g. Admin, Contributor).


The git_login property is used only for USER rule types when specifying a user by their git handle (e.g. GitHub login) instead of their UUID.


The object_rules property contains a list of object rules that define which branches, tags, or pull requests can trigger promotions. Each rule must include the type, match_mode, and pattern properties.


The type property of an object rule can have the following values: BRANCH, TAG, or PR.


The match_mode property plays a crucial role in determining how the pattern matches the name of the git reference, such as a branch or tag. There are three options available for match_mode: ALL, EXACT, or REGEX. However, when it comes to object rules of type PR, there is no requirement to specify the match_mode. This is because any pull request will automatically trigger the promotion if there is an object rule with the type set to PR.


The pattern property is a string used to match the name of the git reference specified by the rule type (branch, tag, or pull request). The pattern is only used for EXACT and REGEX match modes. In EXACT mode, an exact string comparison is performed between the branch/tag name and the pattern. In REGEX mode, the pattern is treated as a regular expression to match the reference name. The regular expressions are Perl-compatible, and you can find more information about the syntax in the the Erlang re module documentation


The active property is a boolean value indicating whether the deployment target is active or inactive. It should not be modified.

bookmark_parameter1, bookmark_parameter2, bookmark_parameter3#

The properties bookmark_parameter1, bookmark_parameter2, and bookmark_parameter3 are string values that represent the names of the promotion parameters. These parameters hold values that can be used to filter deployments in the deployment history.

Let's consider an example: suppose you create a parameterized promotion with an environment parameter that can take values like staging and production. If you connect this promotion to a deployment target where bookmark_parameter1 is set to environment, it enables you to filter the deployment history and display only those promotions where, for instance, staging was passed as the value for the parameter. This feature allows you to conveniently track deployments based on specific parameter values.


The env_vars property is a list of environment variables defined for the deployment target. Each environment variable is defined by its name and value.


The name property represents the name of the environment variable.


The value property represents the value of the environment variable. If the response includes the suffix [md5], this indicates that a hashed value has been received for security reasons.


The files property is a list of files defined for the deployment target. Each file is defined by its path and content.


The path property specifies the path on the machine where the file will be created.


The content property contains the base64-encoded content of the file. If the response includes the suffix [md5], this indicates that a hashed value has been received for security reasons.


The source property represents the path on your host machine of the file you want to assign to the deployment target. It is only used when creating or updating the files property.

An example#

The following YAML code provides an example of a deployment target as returned by the sem get dt 0d4d4184-c80a-4cbb-acdd-b75e3a03f795 command (using the deployment target UUID) or the sem get dt mytest -i a426b4db-1919-483d-926d-06ba1320b209 command (using the deployment target name and project UUID):

$ sem get dt my-dt -p my-project
apiVersion: v1alpha
kind: DeploymentTarget
  id: 0d4d4184-c80a-4cbb-acdd-b75e3a03f795
  name: my-dt
  project_id: a426b4db-1919-483d-926d-06ba1320b209
  organization_id: 7304b7f9-7482-46d4-9b95-3cd5a6ef2e6f
  created_by: 02984c87-efe8-4ea1-bcac-9511a34a3df3
  updated_by: 02984c87-efe8-4ea1-bcac-9511a34a3df3
  created_at: 2023-06-09T05:46:23Z
  updated_at: 2023-06-09T07:46:49Z
  description: new description
  url: newurl321.zyx
  state: CORDONED
  state_message: ""
  - type: ROLE
    subject_id: Contributor
  - type: USER
    subject_id: 02984c87-efe8-03a2-bcac-9511a34a3df3
    git_login: example_login_24ac3
  - type: BRANCH
    match_mode: EXACT
    pattern: main
  - type: TAG
    match_mode: ALL
    pattern: ""
  - type: PR
    match_mode: REGEX
    pattern: .*[feat].*
  active: false
  bookmark_parameter1: b1
  bookmark_parameter2: ""
  bookmark_parameter3: ""
  - name: X
    value: ef836f1a81645fd778adb189377aed1d [md5]
  - path: /home/dev/app/my.conf
    content: 0c2606ba4ac1ee72b5cc6f91648bf28c [md5]
    source: ""

You can find out how to create new deployment targets by visiting our Deployment Targets, and sem command line tool reference documentation.

See Also#