This document introduces the data structures that represent the ssh pipeline. The ssh pipeline is a continuous integration pipeline that executes workloads on remote servers using the ssh protocol.

The Resource interface

The Resource interface is implemented by all top-level objects, including the ssh Pipeline.

1
2
3
4
5
6
7

interface Resource {
  kind: string;
  type: string;
  name: string;
  concurrency: Concurrency;
  depends_on: string[];
}

The kind attribute

Defines the kind of resource, used to identify the resource implementation. This attribute is of type string and is required.

The type attribute

Defines the type of resource, used to identify the resource implementation. This attribute is of type string and is required.

The name attribute

The name of the resource. This value is required and must match [a-zA-Z0-9_-]. This value is displayed in the user interface (non-normative) and is used to identify the pipeline (non-normative).

The concurrency attribute

Defines the concurrency limits for the pipeline stage. This attribute is of type Concurrency and is optional.

The depends_on attribute

Defines a list of pipeline dependencies, used to defer execution of the pipeline until the named pipelines are in a completed state. This attribute is an array of type string and is optional.

The Pipeline object

The Pipeline is the top-level object used to represent the ssh pipeline. The Pipeline object implements the Resource interface.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

class Pipeline : Resource {
  kind:      string;
  type:      string;
  name:      string
  server     Server;
  platform:  Platform;
  workspace: Workspace;
  clone:     Clone;
  steps:     Step[];
  trigger:   Conditions;
}

The kind attribute

The kind of resource. This value must be set to pipeline.

The type attribute

The type of resource. This value must be set to ssh.

The server section

The remote server address and authentication credentials. This attribute is of type Server and is required.

The platform section

The target operating system and architecture on which the pipeline must execute. This attribute is of type Platform and is recommended. If empty, the default operating system and architecture may be linux and amd64 respectively.

The workspace section

The working directory where the source code is cloned and the default working directory for each pipeline step. This attribute is of type Workspace and is optional.

The clone section

Defines the pipeline clone behavior and can be used to disable automatic cloning. This attribute is of type Clone and is optional.

The steps section

Defines the pipeline steps. This attribute is an array of type Step and is required. The array must not be empty and the order of the array must be retained.

The trigger section

The conditions used to determine whether or not the pipeline should be skipped. This attribute is of type Conditions and is optional.

The Server object

The Server object defines the clone behavior for the pipeline.

1
2
3
4
5
6

class Clone {
  host:    string | Secret;
  user:    string | Secret;
  password string | Secret;
  ssh_key  string | Secret;
}

The host attribute

Configures the server host address. The host address may include the port number. This is a required string or Secret value.

The user attribute

Configures the username used to authenticate with the server. This is a required string or Secret value.

The password attribute

Configures the password used to authenticate with the server. This is an optional string or Secret value.

The ssh_key attribute

Configures the ssh key used to authenticate with the server. This is an optional string or Secret value.

The Platform object

The Platform object defines the target os and architecture for the pipeline.

1
2
3
4
5
6

class Platform {
  os:      OS;
  arch:    Arch;
  variant: string;
  version: string;
}

The os attribute

Defines the target operating system. The attribute is an enumeration of type OS and is recommended. If empty the operating system may default to Linux.

The arch attribute

Defines the target architecture. The attribute is an enumeration of type Arch and is recommended. If empty the architecture may default to amd64.

The variant attribute

Defines the architecture variant. This is most commonly used in conjunction with the arm architecture (non-normative) and can be used to differentiate between armv7, armv8, and so on (non-normative).

The version attribute

Defines the operating system version. This is most commonly used in conjunction with the windows operating system (non-normative) and can be used to differentiate between 1809, 1903, and so on (non-normative).

The Clone object

The Clone object defines the clone behavior for the pipeline.

1
2
3
4

class Clone {
  depth:   number;
  disable: boolean;
}

The depth attribute

Configures the clone depth. This is an optional number value. If empty the full repository may be cloned (non-normative).

The disable attribute

Disables cloning the repository. This is an optional boolean value. It can be useful when you need to disable implement your own custom clone logic (non-normative).

The Step object

The Step object defines a pipeline step.

1
2
3
4
5
6
7
8

class Step {
  name:        string;
  failure:     Failure;
  commands:    string[];
  environment: [string, string];
  when:        Conditions;
  depends_on:  string[];
}

The name attribute

The name of the step. This value is required and must match [a-zA-Z0-9_-]. This value is displayed in the user interface (non-normative) and is used to identify the step (non-normative).

The failure attribute

Defines how the system handles failure. The default value is always indicating a failed step always fails the overall pipeline. A value of ignore indicates the failure is ignored. This attribute is of enumeration Failure and is optional.

The commands attribute

Defines a list of shell commands executed on the host machine. This attribute is an array of type string and is required.

The environment attribute

Defines a list of environment variables scoped to the pipeline step. This attribute is of type [string, string] and is optional.

The when section

The conditions used to determine whether or not the step should be skipped. This attribute is of type Conditions and is optional.

The depends_on attribute

Defines a list of steps dependencies, used to defer step execution until the named steps are in a completed state. This attribute is of type string and is optional.

The Conditions object

The Conditions object defines a set of conditions. If any condition evaluates to true its parent object is skipped.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

class Conditions {
  action:   Constraint | string[];
  branch:   Constraint | string[];
  cron:     Constraint | string[];
  event:    Constraint | Event[];
  instance: Constraint | string[];
  ref:      Constraint | string[];
  repo:     Constraint | string[];
  status:   Constraint | Status[];
  target:   Constraint | string[];
}

The action attribute

Defines matching criteria based on the build action. The build action is synonymous with a webhook action (non-normative). This attribute is of type Constraint or an array of type string and is optional.

The branch attribute

Defines matching criteria based on the git branch. This attribute is of type Constraint or an array of type string and is optional.

The cron attribute

Defines matching criteria based on the cron job that triggered the build. This attribute is of type Constraint or an array of type string and is optional.

The event attribute

Defines matching criteria based on the build event. The build event is synonymous with a webhook event (non-normative). This attribute is of type Constraint or an array of type Event and is optional.

The instance attribute

Defines matching criteria based on the instance hostname. This attribute is of type Constraint or an array of type string and is optional.

The ref attribute

Defines matching criteria based on the git reference. This attribute is of type Constraint or an array of type string and is optional.

The repo attribute

Defines matching criteria based on the repository name. This attribute is of type Constraint or an array of type string and is optional.

The status attribute

Defines matching criteria based on the pipeline status. This attribute is of type Constraint or an array of type Status and is optional.

The target attribute

Defines matching criteria based on the target environment. The target environment is typically defined by a promote or rollback event (non-normative). This attribute is of type Constraint or an array of type string and is optional.

The Constraint object

The Constraint object defines pattern matching criteria. If the pattern matching evaluates to false, the parent object is skipped.

1
2
3
4

class Constraint {
  exclude: string[];
  include: string[];
}

The include attribute

List of matching patterns. If no pattern is a match, the parent object is skipped. This attribute is an array of type string and is optional.

The exclude attribute

List of matching patterns. If any pattern is a match, the parent object is skipped. This attribute is an array of type string and is optional.

The Secret object

The Secret defines the named source of a secret.

1
2
3

class Secret {
  from_secret: string;
}

The Concurrency object

The Concurrency object defines the concurrency limits for the named pipeline.

1
2
3

class Concurrency {
  limit: number;
}

The Workspace object

The Workspace object defines the path to which the source code is cloned (non-normative) and the default working directory for each pipeline step (non-normative).

1
2
3

class Workspace {
  path: string;
}

Enums

The Event enum

The Event enum provides a list of pipeline events. This value represents the event that triggered the pipeline.

1
2
3
4
5
6
7
8
9

enum Event {
  cron,
  custom,
  promote,
  pull_request,
  push,
  rollback,
  tag,
}

The Status enum

The Status enum provides a list of pipeline statuses. The default pipeline state is success, even if the pipeline is still running.

1
2
3
4

enum Status {
  failure,
  success,
}

The Failure enum

The Failure enum defines a list of failure behaviors. The value always indicates a failure will fail the parent process. The value ignore indicates the failure is silently ignored.

1
2
3
4

enum Failure {
  always,
  ignore,
}

The OS enum

The OS enum provides a list of supported operating systems.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

enum OS {
  darwin,
  dragonfly,
  freebsd,
  linux,
  netbsd,
  openbsd,
  solaris,
  windows,
}

The Arch enum

The Arch enum provides a list of supported chip architectures.

1
2
3
4
5
6

enum Arch {
  386,
  amd64,
  arm64,
  arm,
}