Skip to content

Drone Pipelines

Summary

Every Aetos repository ships a Drone CI definition at .drone.yml. There is exactly one standard per repository, and there are two types of file, chosen by what the repository produces:

Type File Produces Repos
A — PyPI package templates/drone/python-lib.yaml A wheel + sdist on the private index dagpipe, doc-forge, hexa, mail-intake, mongo-ops, omniread, openapi-first, py-jwt
B — Docker deployment templates/drone/service-docker.yaml An image pushed to the registry and run as a container auth-server, docs, mcp

Both templates run on platform: linux / arm64 with the workspace at /drone/src. Copy the matching template to <repo>/.drone.yml; the Type A file needs no edits, the Type B file needs its placeholders filled in (below).

Conventions: .drone.yml (not .yaml), one file per repo, secrets injected with from_secret — never commit credentials.

Type A — PyPI package (python-lib.yaml)

For internal libraries. The file contains two pipelines:

  1. build-and-publish-pypi — triggered on tag:
  2. check-version — guard: fail unless $DRONE_TAG equals the version in pyproject.toml; then read name / version and query $PIP_REPO_URL/simple/<package>/; if that version already exists, exit 78 and skip the whole build (see 11 – Versioning & Changelog).
  3. quality-gate — install the package with its [dev] extras from the private index, then black --check, ruff check, mypy, pydoclint, pytest.
  4. build-package — python -m build into dist/.
  5. upload-to-private-pypi — twine upload to $PIP_REPO_URL.
  6. backfill-pypi-from-tags — triggered on custom:
  7. fetch-tags — git fetch --tags --force.
  8. build-and-upload-missing — walk every tag in version order, skip the ones already on the index, git checkout the rest, verify tag == pyproject version at that commit, build, and upload. This is the disaster-recovery / replay path.

Secrets: PIP_REPO_URL, PIP_USERNAME, PIP_PASSWORD.

  • Ship as-is. Package name and version come from pyproject.toml, so the same file is reused verbatim across every library.

Type B — Docker deployment (service-docker.yaml)

For services and sites that ship a container image. The file contains two pipelines, each mirroring a repo family:

  1. build-and-deploy-service — triggered on tag (a long-running API/worker service, e.g. auth-server):
  2. fetch-tags — resolve the latest tag into LATEST_TAG.txt; fail if there are no tags.
  3. check-version — guard: fail unless $DRONE_TAG equals the repo-root VERSION file (see 11 – Versioning & Changelog).
  4. check-remote-image — if aetos/<app>:<tag> already exists locally, exit 78 and skip the build.
  5. quality-gate — install from requirements.txt and run black / ruff / mypy / pytest.
  6. build-image — docker build with the private-index build args, tagged aetos/<app>:<tag> and :latest.
  7. push-image — login, re-tag with $REGISTRY_HOST, push both tags.
  8. stop-old — docker rm -f <app>.
  9. run-container — docker run -d --name <app> -p <host>:<container> --restart always with the service's -e environment.
  10. build-and-deploy-site — triggered on push (a static/HTTP site, e.g. docs, mcp): build-image → push-image → stop-old → run-container, with no tag resolution, no quality gate, and no version guard (it ships :latest only).

Secrets: PIP_REPO_URL, PIP_USERNAME, PIP_PASSWORD (service build args), REGISTRY_HOST, REGISTRY_USER, REGISTRY_PASS, plus the service runtime env (for example MONGO_*, JWT_SECRET).

Placeholders to fill in per repo:

Placeholder Meaning Example
<app> service image / container name auth-server
aetos/<app> image repository on the registry aetos/auth-server
<host-port> / <container-port> published : in-image port 9003:8000
<site> site image / container name docs
<ENV_VAR> runtime environment variable MONGO_HOST

What not to do

  • Do not hand-roll a third shape. A repo is either Type A or Type B, never both.
  • Do not inline secrets; always use from_secret.
  • Do not drop the check-version / check-remote-image skip — it guards the index and the running container against duplicate publishes.
  • Do not drop the tag↔version guard. A package needs its pyproject.toml version to equal the tag; a service needs a root VERSION file that equals the tag. See 11 – Versioning & Changelog.
  • Do not rename the pipelines; tooling and runbooks key off build-and-publish-pypi, build-and-deploy-service, and build-and-deploy-site.