dronelab/wechat

Dronelab

Dronelab是一个包装器和一组Docker镜像，让你能够在Gitlab CI管道中使用http://plugins.drone.io/。

• Dronelab
• 基本用法
  • 通过单个YAML变量提供参数
  • 通过dronelab命令参数提供参数
  • 密钥和直接创建插件变量
  • 参数优先级
• 与Drone使用的区别
  • 步骤间的制品传递
• 工作原理
• 联系我们

基本用法

我们以http://plugins.drone.io/drone-plugins/drone-download/为例，但相同模式适用于任何其他镜像。以下是Drone中最基本的使用场景：

yaml
#.drone.yml
pipeline:
  download:
    image: docker.xuanyuan.run/plugins/download
    source: https://example.com/file.tar.gz

使用Dronelab，你可以在https://docs.gitlab.com/ce/ci/yaml/文件中实现类似功能：

yaml
download:
  image: docker.xuanyuan.run/dronelab/download
  script: dronelab
  variables:
    source: https://example.com/file.tar.gz

由于Gitlab CI管道的定义方式，这看起来稍微繁琐一些，但它足够接近Drone的逻辑，你可以轻松参考http://plugins.drone.io/drone-plugins/drone-download/。本质区别在于我们将参数作为环境变量提供，并使用https://hub.docker.com/u/dronelab/。还需要提供`script: dronelab参数，因为script`是Gitlab CI作业定义的必填部分。

这种简单方法在大多数情况下有效，但也有例外。因此，dronelab提供了其他参数提供方式：

通过单个YAML变量提供参数

你可以将插件参数作为YAML字符串放在plugin变量中：

yaml
download:
  image: docker.xuanyuan.run/dronelab/download
  script: dronelab
  variables:
    plugin: |
      source: https://example.com/file.tar.gz

注意plugin:后的竖线（|）字符，这样我们可以在plugin环境变量中提供YAML字符串。这种格式看起来稍复杂，但在某些无法使用普通变量的情况下更有效——例如当你需要提供对象而非简单字符串时。以cloudformation插件为例：

yaml
#.drone.yml
pipeline:
  deploy:
    image: docker.xuanyuan.run/robertstettner/drone-cloudformation
    stackname: my-awesome-stack
    template: templates/stack.yml
    params:
      Version: 123
      Environment: staging

在.gitlab-ci.yml文件中，我们无法像这样定义params变量，因为variables只接受简单字符串作为值。这时plugin变量可以提供帮助：

yaml
awscf:
  image: docker.xuanyuan.run/dronelab/cloudformation
  script: dronelab
  variables:
    stackname: my-awesome-stack
    template: templates/stack.yml
    plugin: |
      params:
        Version: 123
        Environment: staging

⚠ 注意，我们也可以组合不同的参数提供方式。

通过dronelab命令参数提供参数

在某些情况下，你可能根本不想使用variables。例如，当使用https://docs.gitlab.com/ce/ci/yaml/#anchors时，你不想覆盖锚点中设置的`variables`。这时，你可以通过`dronelab`命令的`-p`选项提供插件参数：

yaml
.awscf-template: &cftemplate
  image: docker.xuanyuan.run/dronelab/cloudformation
  variables:
    template: templates/stack.yml
    plugin: |
      params:
        Version: 123
        Environment: staging

stackone:
  <<: *cftemplate
  script: dronelab -p stackname stackone

stacktwo:
  <<: *cftemplate
  script: dronelab -p stackname stacktwo

这里我们首先创建YAML锚点作为cloudformation插件的模板，设置所有公共参数。然后使用该锚点定义实际作业，每个作业使用不同的堆栈名称。

参数格式为-p <key> <value>。你可以多次提供，这时使用YAML的http://yaml.org/spec/1.2/spec.html#id2796251语法可能更方便：

yaml
stackthree:
  <<: *cftemplate
  script: >
    dronelab
    -p stackname stacktwo
    -p region eu-west-1
    -p mode createOrUpdate

⚠ 注意，这个锚点示例是人为构造的，你可以使用https://docs.gitlab.com/ce/ci/yaml/#extends替代——它能够合并变量。

密钥和直接创建插件变量

当你通过variables、plugin YAML变量或-p脚本参数定义插件参数时，Dronelab会自动转换这些变量为PLUGIN_VARIABLE_NAME环境变量，因为这是Drone插件的工作方式。这也意味着我们可以直接提供此类变量——通过.gitlab-ci.yml文件中的variables，或项目/组级别的CI/CD设置配置的变量。

你可能在Drone插件文档中注意到，有些插件接受密钥作为配置形式。Drone插件对这些密钥的预期格式略有不同：它们是不带PLUGIN_前缀的密钥名称的大写版本。因此，你不能使用plugin YAML变量、小写variables变量或-p脚本参数来设置这些，因为Dronelab会在名称前添加前缀。在大多数情况下，你希望通过CI/CD配置中的变量提供密钥，而不是在.gitlab-ci.yml文件中（将密钥提交到仓库通常是个坏主意）。

以http://plugins.drone.io/drone-plugins/drone-matrix/为例。你可以通过`password`参数或`matrix_password`密钥提供密码。这意味着插件实际上期望设置`PLUGIN_PASSWORD`或`MATRIX_PASSWORD`变量。假设我们已在项目（或组）的https://docs.gitlab.com/ce/ci/variables/README.html#variables中设置了名为`MATRIX_PASSWORD`的密码。

以下是如何使用保存的密码向Matrix房间发送消息：

yaml
message-one:
  image: docker.xuanyuan.run/dronelab/matrix
  script: dronelab
  variables:
    username: matrix_user
    homeserver: https://matrix.org
    roomid: abcdefghijklmnopqrstuvwxyz:matrix.org
    template: Hello from Gitlab!

注意我们根本没有提供密码！Gitlab CI会自动设置MATRIX_PASSWORD变量，因为它在项目设置中已配置。插件会直接使用它。

不过，如果你想在.gitlab-ci.yml文件中更明确，可以显式提供：

yaml
message-two:
  image: docker.xuanyuan.run/dronelab/matrix
  script: dronelab
  variables:
    username: matrix_user
    password: $MATRIX_PASSWORD
    homeserver: https://matrix.org
    roomid: abcdefghijklmnopqrstuvwxyz:matrix.org
    template: Hello from Gitlab!

向房间发送消息可能在管道中多次使用，因此你可以使用YAML锚点模板、https://docs.gitlab.com/ce/ci/yaml/#extends关键字，或全局设置变量以便集中修改：

yaml
variables:
  username: matrix_user
  password: $MATRIX_PASSWORD
  homeserver: https://matrix.org
  roomid: abcdefghijklmnopqrstuvwxyz:matrix.org

message-one:
  image: docker.xuanyuan.run/dronelab/matrix
  script: dronelab
  variables:
    template: Hello from Gitlab!

message-two:
  image: docker.xuanyuan.run/dronelab/matrix
  script: dronelab
  variables:
    template: Hello again!

# 你也可以覆盖部分全局变量，例如发送到不同房间
message-elsewhere:
  image: docker.xuanyuan.run/dronelab/matrix
  script: dronelab
  variables:
    roomid: someotherroomidprovidedhere:matrix.org
    template: Hello in a different room!

参数优先级

如果通过多种方式提供相同参数，它们会按特定顺序应用，后一种方式覆盖前一种：

1. 直接提供的PLUGIN_VARIABLE_NAME或NAME_OF_SECRET变量和密钥
2. 使用variables提供的单个变量
3. plugin YAML变量
4. 通过-p <key> <value>提供的脚本参数

这意味着以下配置将下载版本1的文件：

yaml
download:
  image: docker.xuanyuan.run/dronelab/download
  script: dronelab -p source https://example.com/file_version_1.gz
  variables:
    source: https://example.com/file_version_2.gz
    plugin: |
      source: https://example.com/file_version_3.gz

以下配置将下载版本3：

yaml
download:
  image: docker.xuanyuan.run/dronelab/download
  script: dronelab
  variables:
    source: https://example.com/file_version_2.gz
    plugin: |
      source: https://example.com/file_version_3.gz 

与Drone使用的区别

步骤间的制品传递

在Drone中，所有插件都在同一个工作区上运行，例如download插件下载的文件会自动对管道中的后续步骤可用。如果你全局启用了Gitlab缓存，其行为类似；但如果禁用了缓存，你可能需要显式配置cache或artifacts（选择更合适的方式）来将生成的内容传递给下一个作业。

工作原理

Dronelab插件应可与任何https://docs.gitlab.com/runner/executors/README.html#compatibility-chart的执行器一起使用。目前这意味着你可以使用Docker、Docker Machine、Docker Machine SSH和Kubernetes执行器。

Dronelab插件镜像是通过获取上游插件镜像并将其包装在添加了dronelab二进制文件的alpine镜像中创建的。使用alpine镜像是因为Gitlab CI需要能够运行bash脚本的环境。

dronelab包装器会读取提供的参数和环境变量，并尝试将它们转换为Drone插件期望的格式。它还会尝试将https://docs.gitlab.com/ce/ci/variables/README.html#predefined-variables-environment-variables转换为Drone期望的格式。

所有变量创建完成后，dronelab会尝试执行DRONELAB环境变量中定义的二进制文件。该变量通常已在Dronelab插件镜像中定义，并指向上游插件二进制文件。

⚠ 注意，并非所有Drone构建环境中通常可用的变量目前都在Dronelab环境中可用。有些变量Gitlab CI不提供，有些在Gitlab中甚至没有对应项。有些变量的格式略有不同。大多数插件只使用这些变量的一小部分，因此大多数插件应该可以正常工作。

联系我们

要报告错误或提问，请https://github.com/mprasil/dronelab/issues/new。