3.5. CI/CD

Overview

Armada uses Changesets to manage service versions and GitHub Actions to automatically build and publish Docker images when a version is bumped on master.

This guide covers everything you need as a developer to release a new version of a service.

Prerequisites

• Node.js installed (for Changesets CLI)
• Push access to the master branch (or permission to merge PRs)
• Run npm install at the repository root at least once to install the Changesets CLI

Services Managed by the Pipeline

See the Services Reference for the documentation of each service.

Releasing a New Version

Step 1 — Create a Changeset

From the repository root, run:

npx changeset

The CLI will prompt you to:

1. Select the affected service(s) — use arrow keys and space to select one or more packages.
2. Choose a bump type for each selected package:
   • patch — bug fixes, minor tweaks (1.0.0 → 1.0.1)
   • minor — new features, backward-compatible changes (1.0.0 → 1.1.0)
   • major — breaking changes (1.0.0 → 2.0.0)
3. Write a summary — a short description of what changed (this goes into the changelog).

This creates a new markdown file inside the .changeset/ directory. You can create multiple changesets before releasing — they will all be applied together.

Step 2 — Apply the Version Bump

When you are ready to release, run:

npx changeset version

This command:

• Reads all pending changeset files in .changeset/
• Bumps the version field in each affected package.json
• Updates (or creates) a CHANGELOG.md for each affected service
• Deletes the consumed changeset files

Review the changes to make sure the version bumps are correct.

Step 3 — Commit and Push

git add .
git commit -m "bump: <service-name> vX.Y.Z"
git push origin master

Once pushed to master, the GitHub Actions pipeline automatically detects the version change and builds the new Docker image.

What Happens After You Push

Two independent GitHub Actions workflows run on every push to master:

Unit Tests (unit-tests.yml)

This workflow also runs on every pull request targeting master.

Push to master / Open PR
      │
      ▼
Setup Python 3.10 + system deps (FreeTDS, unixODBC)
      │
      ▼
Install pytest, pytest-asyncio, httpx
      │
      ▼
Install requirements for: agent, backend, orchestrator,
proxy-provider, fingerprint-provider + lib/fantomas
      │
      ▼
Run  pytest tests/unit -v

The tests/unit/ directory mirrors the service structure:

Docker Publish (docker-publish.yml)

This workflow only triggers when a services/**/package.json file is modified (i.e. a version bump).

Push to master (with version change)
      │
      ▼
Detect modified services (compare package.json versions)
      │
      ▼
Build Docker image for each changed service
      │
      ▼
Push to Docker Hub (tagged with version + latest)
      │
      ▼
Create Git tag: <image-name>@<version>

You can monitor both workflows in the Actions tab of the GitHub repository.

Checking Current Service Versions

A utility script list-versions.js is available at the repository root to list the name, version, and path of every package (services and libraries such as fantomas) in a single table.

From the repository root, run:

node list-versions.js

This recursively scans all directories (skipping node_modules and .git), reads every package.json it finds, and prints a formatted table:

┌─────────┬──────────────────────────────────┬─────────┬──────────────────────────────────────────┐
│ (index) │ name                             │ version │ path                                     │
├─────────┼──────────────────────────────────┼─────────┼──────────────────────────────────────────┤
│    0    │ 'armada-agent'                   │ '1.0.0' │ '/home/user/armada/services/agent'        │
│    1    │ 'armada-backend'                 │ '1.2.0' │ '/home/user/armada/services/backend'      │
│    2    │ 'fantomas'                       │ '0.5.0' │ '/home/user/armada/lib/fantomas'          │
│   ...   │ ...                              │  ...    │ ...                                      │
└─────────┴──────────────────────────────────┴─────────┴──────────────────────────────────────────┘

Common Scenarios

Bumping multiple services at once

Run npx changeset and select multiple packages when prompted. Each package can have a different bump type.

Undoing a changeset before it is applied

Simply delete the generated markdown file inside .changeset/. It has not affected any version yet.

Checking pending changesets

Look at the .changeset/ directory. Any .md file (other than README.md) is a pending changeset waiting to be applied by npx changeset version.

Credentials

The pipeline uses the following GitHub secrets (configured by an admin):