本文档介绍了 exec 流水线 的数据结构表现。The exec pipeline is a continuous integration pipeline that executes commands directly on the host machine.

Resource 接口 (interface)

所有顶层对象，包括 exec Pipeline 对象都要实现 Resource 接口。

1
2
3
4
5
6
7

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

kind 属性 (attribute)

定义资源种类，用于标识资源实现。该属性是一个必填 (required) 的 string 类型。

type 属性 (attribute)

定义资源类型，用于标识资源实现。该属性是一个必填 (required) 的 string 类型。

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)

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

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 exec pipeline. The Pipeline object implements the Resource interface.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

class Pipeline : Resource {
  kind:      string;
  type:      string;
  name:      string
  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 exec.

platform 节 (section)

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

workspace 节 (section)

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

clone 节 (section)

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

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)

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

Platform 对象 (object)

The Platform object defines the target os and architecture for the pipeline and is used to route the pipeline to the correct instance (non-normative).

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)

This attribute is of enumeration Failure and is optional. 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.

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)

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

when 节 (section)

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

depends_on 属性 (attribute)

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

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)

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

branch 属性 (attribute)

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

cron 属性 (attribute)

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

event 属性 (attribute)

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

instance 属性 (attribute)

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

ref 属性 (attribute)

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

repo 属性 (attribute)

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

status 属性 (attribute)

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

target 属性 (attribute)

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

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.

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