本文档介绍了 docker 流水线 的数据结构表现。The Docker pipeline is a continuous integration pipeline that executes pipeline steps inside isolated Docker containers.

Resource 接口 (interface)

所有顶层对象，包括 docker 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)

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

class Pipeline : Resource {
  kind:      string;
  type:      string;
  name:      string;
  platform:  Platform;
  workspace: Workspace;
  clone:     Clone;
  steps:     Step[];
  volumes:   Volume[];
  node:      [string, string];
  trigger:   Conditions;

  image_pull_secrets: string[]
}

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

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.

node 属性 (attribute)

Defines key value pairs used to route the pipeline to a specific runner or group of runners. This attribute is of type [string, string] and is optional.

trigger 节 (section)

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

image_pull_secrets 属性 (attribute)

The list of secrets used to pull private Docker images; This attribute is an array of type string and is optional.

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
 9
10
11
12
13
14
15
16
17

class Step {
  command:      string[];
  commands:     string[];
  detach:       boolean;
  entrypoint:   string[];
  environment:  [string, string | Secret];
  failure:      Failure;
  image:        string;
  name:         string;
  network_mode: string;
  privileged:   boolean;
  pull:         Pull;
  user          string;
  volumes:      Volume[];
  when:         Conditions;
  depends_on:   string[];
}

commands 属性 (attribute)

Defines a list of shell commands executed inside the Docker container. The commands are executed using the default container shell (non-normative) as the container ENTRYPOINT. This attribute is an array of type string and is required.

command 属性 (attribute)

Overrides the image COMMAND. This should only be used with service containers and cannot not be used with the commands attribute. This attribute is an array of type [string] and is optional.

detach 属性 (attribute)

The detach attribute instructions the system to start the Docker container and then run in the background. This value is of type boolean and is optional.

entrypoint 属性 (attribute)

Overrides the image ENTRYPOINT. This should only be used with service containers and cannot not be used with the commands attribute. This attribute is an array of type [string] and is optional.

environment 属性 (attribute)

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

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.

image 属性 (attribute)

The name of the docker image. The image name should include the tag and will default to the latest tag if unspecified. This value is of type string and is required.

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

network_mode 属性 (attribute)

Overrides the default network to which the Docker container is attached. For example host or bridge. This attribute is of type string and is optional.

privileged 属性 (attribute)

Overrides the default Docker security policy and grants the container nearly full access to the host machine. This attribute is of type boolean and is optional.

pull 属性 (attribute)

Defines how and when the system should pull images. This attribute is of enumeration Pull and is optional.

user 属性 (attribute)

Overrides the default username or uid used when executing the pipeline commands or entrypoint. This attribute is of type 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,
}

Pull 枚举 (enum)

The Pull enum defines if and when a docker image should be pull from the registry.

1
2
3
4
5

enum Pull {
  always,
  never,
  if-not-exists,
}

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