czon/azdo-agent

Azure Pipelines代理Docker容器

这是一个基于Docker的项目，用于自动生成指定版本的Azure DevOps Pipelines代理Docker镜像。生成的Docker镜像应作为项目特定代理的基础，根据项目流水线需求进行定制。

说明：Windows镜像目前未维护。

镜像概述和主要用途

该镜像提供预配置的Azure Pipelines代理环境，旨在简化Azure DevOps流水线中代理的部署和管理。通过环境变量即可配置代理连接信息、名称、池和工作目录等，支持安全传递敏感信息（如令牌、密码），适用于需要在Docker环境中运行定制化Azure Pipelines代理的场景。

核心功能和特性

• 灵活配置：通过环境变量自定义代理名称、池、工作目录等参数
• 安全认证：支持文件挂载方式传递敏感信息（如令牌文件、密码文件），避免环境变量明文暴露
• 环境管理：可配置忽略、排除或包含特定环境变量，控制代理能力和运行时环境
• 行为控制：支持单任务后自动注销代理（需注意已知bug）

使用场景和适用范围

适用于需要在Docker容器中部署Azure Pipelines代理的CI/CD场景，特别是：

• 需要隔离和定制化代理环境的项目
• 需安全管理敏感认证信息（如个人访问令牌）的场景
• 需要灵活配置代理能力和运行时环境的流水线

详细使用方法和配置说明

基本使用方法

Azure Pipelines代理必须使用账户连接信息启动，通过以下环境变量提供：

基本运行命令

运行默认Azure Pipelines代理镜像，连接到特定Azure DevOps账户：

bash
docker run \
  -e AZDO_URL=<url> \
  -e AZDO_TOKEN=<pat> \
  -it czon/azdo-agent

安全传递敏感信息

推荐通过挂载文件传递个人访问令牌，使用AZDO_TOKEN_FILE指定文件路径：

bash
docker run \
  -v /path/to/my/token:/azdo-token \
  -e AZDO_URL=<url> \
  -e AZDO_TOKEN_FILE=/azdo-token \
  -it czon/azdo-agent

同理，AZDO_PASSWORD也建议通过AZDO_PASSWORD_FILE文件挂载方式传递。

自定义代理配置

通过以下环境变量进一步配置代理：

• AZDO_AGENT：代理名称（默认："$(hostname)"）
• AZDO_POOL：代理池名称（默认："Default"）
• AZDO_WORK：代理工作目录（默认："_work"）

AZDO_AGENT和AZDO_WORK支持容器内shell变量展开，AZDO_AGENT优先计算，AZDO_WORK可引用其值。

示例：运行Ubuntu 18.04版本代理，自定义名称、池和工作目录：

bash
docker run \
  -e AZDO_URL=<url> \
  -e AZDO_TOKEN=<pat> \
  -e AZDO_AGENT='$(hostname)-agent' \
  -e AZDO_POOL=mypool \
  -e AZDO_WORK='/var/azdo/$AZDO_AGENT' \
  -v /var/azdo:/var/azdo \
  -it czon/azdo-agent:ubuntu-18.04

配置参数详解

必选参数

• AZDO_URL
  Azure DevOps账户的完整URL（例如："https://dev.azure.com/czon/" 或 "https://tfs.company.com/tfs/"）。

• 基于令牌的认证（推荐）

  • AZDO_TOKEN：个人访问令牌（PAT），需至少拥有代理池（读取、管理） 权限
  • AZDO_TOKEN_FILE：包含令牌的文件路径（替代AZDO_TOKEN，更安全）

• 基于用户名密码的认证（不推荐）

  • AZDO_USER：用户名
  • AZDO_PASSWORD：密码
  • AZDO_PASSWORD_FILE：包含密码的文件路径（替代AZDO_PASSWORD，更安全）

可选参数

环境配置

• AZDO_AGENT
  代理在Azure DevOps中显示的名称（默认："$(hostname)"）。

• AZDO_WORK
  代理工作目录路径（默认："/azdo/agent/_work/"）。

• AZDO_ENV_IGNORE
  逗号分隔的环境变量列表，代理扫描能力时将忽略这些变量（适用于不希望出现在能力列表中的Dockerfile变量）。

• AZDO_ENV_EXCLUDE
  逗号分隔的环境变量列表，将从代理运行环境中排除（适用于运行时不需要的敏感变量）。

• AZDO_ENV_INCLUDE
  逗号分隔的环境变量列表，将添加到代理运行环境中（例如："Agent.Project=Sample Project"，可用于作业需求）。

行为配置

• AZDO_AGENT_DISPOSE
  代理仅处理一个作业，完成后关闭并注销自身。

  注意：目前代理存在bug，导致此选项可靠性不佳！
  详见：https://github.com/microsoft/azure-pipelines-agent/issues/2332

开发指南

环境准备

注意：推荐开发环境为Windows集成WSL Bash。

1. 下载并安装Docker
2. 若使用Windows，安装Ubuntu Bash（Windows应用商店）
3. 开始开发！

构建

update.sh脚本从*.templates文件生成Dockerfile；
运行build.sh从Dockerfile构建镜像。

运行

运行run.sh可启动容器并注册到Azure DevOps。

示例：

bash
./run.sh czon/azdo-agent:ubuntu-18.04-2.155.1 -s https://dev.azure.com/czon/ -n TestAgent01 -p DockerSamples -c -d -i

贡献

基于Linux或Windows构建自定义Dockerfile/镜像：

1. 添加模板文件（创建dockerfile.template和版本文件）
2. 在update.sh中注册模板，运行脚本生成Dockerfile
3. 运行build.sh从所有Dockerfile构建镜像

作者

• Kirsten Kluge - 初始工作 - https://github.com/kirkone

查看参与项目的https://github.com/codez-one/docker-azure-pipelines-agent/graphs/contributors%E3%80%82

许可证

本项目采用MIT许可证 - 详见LICENSE文件。

鸣谢

基于以下项目：

• https://github.com/microsoft/vsts-agent-docker
• Microsoft文档