dronelab/wechat

Dronelab

Dronelab是一个包装器和一组Docker镜像，让你能够在Gitlab CI管道中使用Drone CI插件。

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

基本用法

我们以Download插件为例，但相同模式适用于任何其他镜像。以下是Drone中最基本的使用场景：

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

使用Dronelab，你可以在.gitlab-ci.yml文件中实现类似功能：

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

由于Gitlab CI管道的定义方式，这看起来稍微繁琐一些，但它足够接近Drone的逻辑，你可以轻松参考上游文档。本质区别在于我们将参数作为环境变量提供，并使用https://hub.docker.com/u/dronelab/%E3%80%82%E8%BF%98%E9%9C%80%E8%A6%81%E6%8F%90%E4%BE%9B%60script: dronelab参数，因为script`是Gitlab CI作业定义的必填部分。

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

通过单个YAML变量提供参数

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

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

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

yaml
#.drone.yml
pipeline:
  deploy:
    image: 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: dronelab/cloudformation
  script: dronelab
  variables:
    stackname: my-awesome-stack
    template: templates/stack.yml
    plugin: |
      params:
        Version: 123
        Environment: staging

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

通过dronelab命令参数提供参数

在某些情况下，你可能根本不想使用variables。例如，当使用YAML锚点时，你不想覆盖锚点中设置的variables。这时，你可以通过dronelab命令的-p选项提供插件参数：

yaml
.awscf-template: &cftemplate
  image: 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的折叠样式语法可能更方便：

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

⚠ 注意，这个锚点示例是人为构造的，你可以使用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文件中（将密钥提交到仓库通常是个坏主意）。

以Matrix插件为例。你可以通过password参数或matrix_password密钥提供密码。这意味着插件实际上期望设置PLUGIN_PASSWORD或MATRIX_PASSWORD变量。假设我们已在项目（或组）的变量CI/CD配置中设置了名为MATRIX_PASSWORD的密码。

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

yaml
message-one:
  image: 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: dronelab/matrix
  script: dronelab
  variables:
    username: matrix_user
    password: $MATRIX_PASSWORD
    homeserver: https://matrix.org
    roomid: abcdefghijklmnopqrstuvwxyz:matrix.org
    template: Hello from Gitlab!

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

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

message-one:
  image: dronelab/matrix
  script: dronelab
  variables:
    template: Hello from Gitlab!

message-two:
  image: dronelab/matrix
  script: dronelab
  variables:
    template: Hello again!

# 你也可以覆盖部分全局变量，例如发送到不同房间
message-elsewhere:
  image: 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: 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: 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插件应可与任何支持image关键字的执行器一起使用。目前这意味着你可以使用Docker、Docker Machine、Docker Machine SSH和Kubernetes执行器。

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

dronelab包装器会读取提供的参数和环境变量，并尝试将它们转换为Drone插件期望的格式。它还会尝试将预定义变量转换为Drone期望的格式。

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

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

联系我们

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