Skip to main content

Deployment Targets YAML

This page describes the YAML syntax used to configure deployment targets (environments).

Overview​

Deployment targets enable the enforcement of strict conditions for triggering pipeline promotions.

You can restrict who and when a promotion can be triggered. 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 for multiple promotions.

apiVersion​

Indicates the version of the syntax used.

The only supported value is: v1alpha

kind​

Determines the type of resource to create.

For deployment targets, the value is: DeploymentTarget

metadata​

Defines metadata properties for the deployment target.

Contains the following values:

id​

This property is automatically generated. It is a unique identification for the deployment target.

name​

A descriptive name for the deployment target.

The name should only include alphanumerical characters, dashes, underscores, and dots.

project_id​

This property identifies the project to attach this deployment target. The value must be a valid project ID.

organization_id​

This property identifies the organization to which this deployment target belongs. The value must be a valid organization ID.

created_by​

The unique ID for the individual that created the deployment target.

created_at​

The UTC time when the deployment target was created. Automatically populated by Semaphore.

updated_by​

The unique ID for the individual that last updated the deployment target.

updated_at​

The UTC time when the deployment target was last updated. Automatically populated by Semaphore.

description​

A string to describe the deployment target.

url​

A URL string associated with the deployment target.

spec​

The spec property contains a list of deployment target properties.

state​

Indicates the state of the deployment target. The value should not be modified.

Possible values are:

  • SYNCING
  • USABLE
  • UNUSABLE
  • CORDONED

state_message​

Provides a string message associated with the deployment target state.

active​

A boolean value indicates if the deployment target is active. It should not be modified.

bookmark_parameter1​

This property can hold values to be used as filters for the deployment history.

For instance, if you set the parameter value to environment and then create a parameterized promotion with environment: ['staging', 'production'], you can use the filtering function in the Semaphore website to view deployment history per environment.

bookmark_parameter2​

This property can hold values to be used to filter the deployment history. Works just like bookmark_parameter1.

bookmark_parameter3​

This property can hold values to be used to filter the deployment history. Works just like bookmark_parameter1.

env_vars​

A list of environment variables for the deployment target.

Each item list consists of a pair of properties:

  • name: the name of the environment variable
  • value: the value of the variable

files​

This property consists of a list of files to be used in the deployment target.

Each item in the list consists of these properties:

  • path: path to the file in the job environment
  • content: base64 encoded content of the file. If the value includes the suffix [md5], this indicates that a hashed value has been received for security reasons
  • source: 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 file property

subject_rules​

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 item in the list can contain these properties:

type​

Used to define subject rules in the deployment target. The contents of this property are a list with rules to allow deployment targets to be used.

Semaphore processes the rules in the supplied order and allows the promotion when one rule is matched.

The type property can take the following values:

subject_id​

This property is used in combination with type: USER and type: ROLE.

Allow users to add their user IDs.

To allow roles, add their role name, e.g. Admin or Contributor.

git_login​

This property is used in combination with type: USER.

It defines the Git username in GitHub or BitBucket that can trigger the promotion.

This property can be used instead of subject_id.

object_rules​

The object_rules property holds a list of object rules that determine when a promotion can be triggered.

Each item in the list can contain these properties:

type​

Used to define object rules in the deployment target. The contents of this property are a list with rules to allow deployment targets to be used.

Semaphore processes the rules in the supplied order and allows the promotion when one rule is matched.

The type property can take the following values:

  • BRANCH: evaluate Git branch names
  • TAG: evaluate Git tag names
  • PR: allow pull requests

match_mode​

Determines what type of matching is used in pattern matching the object rule. This property is used in conjunction with type.

The possible values for this property are:

  • ALL: do not perform pattern matching
  • EXACT: matches string literals only
  • REGEX: allows regular expression matches.
note

The regular expressions are Perl-compatible, and you can find more information about the syntax in the the Erlang re module documentation

pattern​

This property defines the string used to match the rule. It is only used when match_mode: EXACT or match_mode: REGEX.

The value of pattern is evaluated according to the match_mode and if a match is found the rule passes.

This property is used to define the Git branch and tag names.

note

When type: PR the pattern and match_mode are ignored. The rule passes for all pull requests

Examples​

The following example provides the definition of a deployment target as returned by sem get dt <deployment-target-id>.

Example
apiVersion: v1alpha
kind: DeploymentTarget
metadata:
  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
spec:
  state: CORDONED
  state_message: ""
  subject_rules:
  - type: ROLE
    subject_id: Contributor
  - type: USER
    subject_id: 02984c87-efe8-03a2-bcac-9511a34a3df3
    git_login: example_login_24ac3
  object_rules:
  - 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: ""
  env_vars:
  - name: X
    value: ef836f1a81645fd778adb189377aed1d [md5]
  files:
  - path: /home/dev/app/my.conf
    content: 0c2606ba4ac1ee72b5cc6f91648bf28c [md5]
    source: ""

See also​