epicsoft/azp-agent repository overview

⁠Azure Pipelines agent

This Docker image is managed and kept up to date by epicsoft LLC⁠.

Self-hosted agents for Azure Pipelines⁠ in a container, built after Microsoft's instructions: the container registers itself in your agent pool, runs jobs and removes itself again when it stops. The image brings the Azure CLI, git, jq and curl; the agent itself is downloaded at start in the version your Azure DevOps organization hands out. On Ubuntu 26.04 or Alpine, for linux/amd64 and linux/arm64, with versioned releases you can pin.

• Base images: https://hub.docker.com/_/ubuntu⁠ (ubuntu:26.04) and https://hub.docker.com/_/python⁠ (python:3.14-alpine), platforms linux/amd64 and linux/arm64
• Instructions this image follows: https://learn.microsoft.com/en-us/azure/devops/pipelines/agents/docker⁠
• Dockerfiles: https://gitlab.com/epicsoft-networks/azp-agent/-/blob/main/Dockerfile.ubuntu26.04⁠ and https://gitlab.com/epicsoft-networks/azp-agent/-/blob/main/Dockerfile.alpine⁠
• Repository: https://gitlab.com/epicsoft-networks/azp-agent⁠, mirrored to GitHub⁠ — issues are welcome on both; code changes only as merge requests on GitLab, the mirror overwrites anything pushed to GitHub
• Container registry: https://gitlab.com/epicsoft-networks/azp-agent/container_registry⁠
• Docker Hub: https://hub.docker.com/r/epicsoft/azp-agent⁠
• Changelog: https://gitlab.com/epicsoft-networks/azp-agent/-/blob/main/CHANGELOG.md⁠
• License: MIT

⁠Versions

Released through a git tag X.Y.Z. A release is built once and never changed afterwards, so a pipeline that pins it runs on the same Azure CLI and the same system packages every time. The changelog names what each release contains.

No longer built: ubuntu22.04 and ubuntu22.04-latest stay on Docker Hub as they were on 2026-10-14.

A pinned image does not pin the agent: it is downloaded when the container starts, in the version your organization offers. Its version is in the job log of every run.

⁠Quick start

Create a personal access token with the scope Agent Pools (read, manage), then:

docker run -d --name azp-agent \
  -e AZP_URL="https://dev.azure.com/<organization>" \
  -e AZP_TOKEN="<personal access token>" \
  -e AZP_POOL="<agent pool>" \
  -e AZP_AGENT_NAME="docker-agent-1" \
  epicsoft/azp-agent:1.0.0

The token can come from a file instead, which keeps it out of docker inspect:

docker run -d --name azp-agent \
  -e AZP_URL="https://dev.azure.com/<organization>" \
  -e AZP_TOKEN_FILE=/run/secrets/azp_token \
  -v /srv/azp/token:/run/secrets/azp_token:ro \
  -e AZP_POOL="<agent pool>" \
  epicsoft/azp-agent:1.0.0

One job per container: arguments after the image name go to the agent's run.sh. With --once the agent takes a single job and exits - together with --rm and a restart policy of the orchestrator, every job gets a fresh container.

docker run --rm -e AZP_URL=... -e AZP_TOKEN_FILE=... epicsoft/azp-agent:1.0.0 --once

⁠Environment variables

The agent runs as user agent (uid 1000) in /azp. Microsoft describes the variables in its instructions⁠.

⁠Ubuntu or Alpine

When in doubt, take Ubuntu: pipeline tasks often download tools built for glibc.

⁠Installed packages

Both images: ca-certificates, curl, git, jq and ICU for the agent, plus the Azure CLI. Packages are upgraded at every build, so the image does not wait for the next base image to get their security fixes.

⁠Reporting problems

Issues are welcome on GitLab⁠ and GitHub⁠. Please report a security problem as a confidential issue on GitLab instead of a public one. Problems of the agent itself belong to Microsoft⁠.

⁠License

MIT⁠ — Copyright (c) 2025-2026 epicsoft LLC / Alexander Schwarz

The MIT license applies only to files created by epicsoft LLC. Third-party software in the image — the Azure Pipelines agent, the Azure CLI, the Ubuntu, Alpine and Python packages and the official base images — remains under its own licenses. start.sh follows the script in Microsoft's instructions.