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.

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[];
}

kind 属性 (attribute)

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

type 属性 (attribute)

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

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

concurrency 属性 (attribute)

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

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.

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;
}

kind 属性 (attribute)

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

type 属性 (attribute)

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

server 节 (section)

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

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.

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.

clone 节 (section)

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

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.

trigger 节 (section)

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

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;
}

host 属性 (attribute)

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

user 属性 (attribute)

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

password 属性 (attribute)

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

ssh_key 属性 (attribute)

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

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;
}

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.

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.

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

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

Clone 对象 (object)

The Clone object defines the clone behavior for the pipeline.

1
2
3
4

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

depth 属性 (attribute)

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

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

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[];
}

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

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.

commands 属性 (attribute)

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

environment 属性 (attribute)

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

when 节 (section)

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

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.

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[];
}

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.

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.

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.

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.

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.

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.

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.

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.

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.

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[];
}

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.

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.

Secret 对象 (object)

The Secret defines the named source of a secret.

1
2
3

class Secret {
  from_secret: string;
}

Concurrency 对象 (object)

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

1
2
3

class Concurrency {
  limit: number;
}

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

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,
}

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,
}

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,
}

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,
}

Arch 枚举 (enum)

The Arch enum provides a list of supported chip architectures.

1
2
3
4
5
6

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