bitsbeats/drone-tree-config

Drone Tree Config

镜像概述和主要用途

Drone Tree Config是一个Drone扩展，用于支持包含多个.drone.yml文件的单体仓库。该扩展会检查每个更改的文件，在文件所在目录或任何父目录中查找.drone.yml配置文件。Drone将使用第一个匹配的.drone.yml，或可选地将所有匹配的配置合并为多机构建。官方Docker镜像地址：https://hub.docker.com/r/bitsbeats/drone-tree-config%E3%80%82

核心功能和特性

• 多配置文件支持：在单体仓库中管理多个.drone.yml配置文件
• 智能匹配机制：根据更改文件自动查找对应目录或父目录中的配置文件
• 灵活构建模式：支持使用第一个匹配配置或合并多个配置为多机构建
• 多平台兼容：支持Github、Gitlab和Bitbucket代码托管平台
• 可配置性：提供多种环境变量配置选项，满足不同场景需求

限制

当前支持以下代码托管平台：

• Github
• Gitlab
• Bitbucket（通过https://github.com/bitsbeats/drone-tree-config/pull/4%E6%94%AF%E6%8C%81%EF%BC%89

使用场景和适用范围

适用于需要在单体仓库中按目录维护多个CI/CD配置的场景，尤其适合大型项目或多模块项目，可实现基于代码变更的定向构建，提高CI/CD效率。

使用方法和配置说明

环境变量

通用配置

• PLUGIN_CONCAT：是否将所有找到的配置合并为多机构建，默认为false
• PLUGIN_FALLBACK：当未检测到更改时是否重建所有.drone.yml，默认为false
• PLUGIN_MAXDEPTH：在回退模式下搜索.drone.yml的最大深度，默认为2（仍能找到/a/b/.drone.yml）
• PLUGIN_DEBUG：设为true启用调试消息，默认为false
• PLUGIN_ADDRESS：插件Web服务器监听地址，默认为:3000
• PLUGIN_SECRET：与Drone共享的密钥，可使用openssl rand -hex 16生成
• PLUGIN_ALLOW_LIST_FILE：（可选）正则模式文件路径，用于匹配仓库slug，默认为空（匹配所有仓库）
• PLUGIN_CACHE_TTL：（可选）缓存条目的生存时间，大于0s时启用内存缓存
• PLUGIN_CONSIDER_FILE：（可选）指定考虑文件名称，仅考虑该文件中列出的.drone.yml文件

后端特定配置

• SERVER：自定义SCM服务器（Gitlab/Bitbucket也使用此配置）

GitHub

• GITHUB_TOKEN：GitHub个人访问令牌，仅需repo权限，详见https://help.github.com/en/articles/creating-a-personal-access-token-for-the-command-line

GitLab

• GITLAB_TOKEN：GitLab个人访问令牌，仅需read_repository权限，详见此处

Bitbucket

• BITBUCKET_AUTH_SERVER：自定义认证服务器（为空时使用SERVER）
• BITBUCKET_CLIENT：Bitbucket访问凭证
• BITBUCKET_SECRET：Bitbucket访问凭证

若未设置PLUGIN_CONCAT，将使用第一个找到的.drone.yml

Docker Compose示例

yaml
version: '2'
services:
  drone-server:
    image: drone/drone
    ports:
      - 8000:80
    volumes:
      - /var/lib/drone:/data
      - /var/run/docker.sock:/var/run/docker.sock
    links:
      - drone-tree-config
    restart: always
    environment:
      - DRONE_OPEN=true
      - DRONE_SERVER_PROTO=https
      - DRONE_SERVER_HOST=
      - DRONE_GITHUB=true
      - DRONE_GITHUB_SERVER=https://github.com
      - DRONE_GITHUB_CLIENT_ID=
      - DRONE_GITHUB_CLIENT_SECRET=
      - DRONE_GIT_ALWAYS_AUTH=true
      - DRONE_SECRET=
      - DRONE_RUNNER_CAPACITY=2

      - DRONE_YAML_ENDPOINT=http://drone-tree-config:3000
      - DRONE_YAML_SECRET=<SECRET>

  drone-tree-config:
    image: bitsbeats/drone-tree-config
    environment:
      - PLUGIN_DEBUG=true
      - PLUGIN_CONCAT=true
      - PLUGIN_FALLBACK=true
      - PLUGIN_SECRET=<SECRET>
      - GITHUB_TOKEN=<GITHUB_TOKEN>
    restart: always

请根据需要修改 Secrets（``）、<SECRET> 和 <GITHUB_TOKEN>。<SECRET> 用于Drone和drone-tree-config之间的通信。

通过正则匹配启用仓库

默认情况下，插件匹配所有仓库slug。若需仅为特定仓库启用插件，可通过指定PLUGIN_ALLOW_LIST_FILE开启正则匹配。

• 正则匹配规则需符合https://github.com/google/re2/wiki/Syntax语法
• 每行一个规则
• 空行将被忽略
• 以#开头的行视为注释（将被忽略）

更新后的docker-compose配置：

yaml
  drone-tree-config:
    image: bitsbeats/drone-tree-config
    environment:
      - PLUGIN_DEBUG=true
      - PLUGIN_CONCAT=true
      - PLUGIN_FALLBACK=true
      - PLUGIN_SECRET=<SECRET>
      - GITHUB_TOKEN=<GITHUB_TOKEN>
      - PLUGIN_ALLOW_LIST_FILE=/drone-tree-config-matchfile
    restart: always
    volumes:
      - /var/lib/drone/drone-tree-config-matchfile:/drone-tree-config-matchfile

示例文件：drone-tree-config-matchfile

text
^bitbeats/.*$
^myorg/myrepo$

• 匹配bitbeats组织下的所有仓库
• 匹配myorg/myrepo仓库

考虑文件

若定义了PLUGIN_CONSIDER_FILE，drone-tree-config将先读取目标文件内容，仅考虑其中指定的.drone.yml文件。

根据仓库的大小和复杂度，使用"考虑文件"可显著减少对提供商（github、bitbucket等）的API调用次数，降低速率限制风险并减少处理时间。

配置示例：

yaml
   - PLUGIN_CONSIDER_FILE=.drone-consider

本地Git仓库结构示例：

shell
$ tree -a my-repo-clone/
 my-repo-clone/
 ├── .drone-consider
 ├── foo
 │   └── .drone.yml
 ├── bar
 │   └── .drone.yml
 └── baz

.drone-***文件内容：

shell
$ cat my-repo-clone/.drone-consider
foo/.drone.yml
bar/.drone.yml

"考虑文件"的缺点是需要保持同步。建议在每个.drone.yml中添加一个步骤来验证"考虑文件"与仓库实际内容同步，例如比较find ./ -name .drone.yml的输出与"考虑文件"内容。

缓存

若定义了PLUGIN_CACHE_TTL，drone-tree-config将利用内存缓存匹配入站请求与缓存中的请求。找到匹配时返回缓存响应，缓存条目在达到TTL后过期并被移除。

示例（30分钟后过期）：

yaml
 - PLUGIN_CACHE_TTL=30m

根据仓库的大小和复杂度，使用缓存可显著减少对提供商的API调用次数，降低速率限制风险并减少处理时间。