Release Management: Track Every Deployment Across Your Architecture

Two months ago, I sat in on a post-mortem where the central question was deceptively simple: "What version of the Payment Service is running in production right now?"

Four people gave three different answers. One checked the GitHub releases page. Another opened ArgoCD. A third scrolled through the Slack deploy channel. The fourth—the one who'd actually deployed it—was on vacation.

This wasn't a startup. This was a team with a mature CI/CD pipeline, good tagging practices, and a well-maintained architecture diagram in Archyl. The diagram told you exactly which systems existed, how they connected, what protocols they spoke. It just couldn't tell you what version of anything was actually running. Anywhere.

That gap has been bothering me for a while. Architecture documentation tells you the structure of a system. Deployment history tells you the state of a system. These two things should live together. Today, they do.

Releases, Linked to Architecture

Archyl's Release Management tracks deployments as first-class objects in your architecture workspace. A release has a version, a status, an environment, a changelog, and—critically—a link to the C4 element it belongs to.

That last part is what makes this different from your CI/CD dashboard. A GitHub Actions run tells you that v2.4.0 was deployed. But deployed where, in the context of your architecture? Which system? Which container? Archyl's releases answer that by connecting deployment events directly to the systems and containers on your C4 diagram.

When you open a system's detail panel, you see its recent releases alongside its relationships, ADRs, and API contracts. The architecture diagram becomes a living map—not just of what exists, but of what shipped and when.

Three Ways to Ingest

We didn't want release tracking to mean more manual work. If you're already deploying through a pipeline, releases should flow into Archyl automatically.

GitHub Actions — We publish an official GitHub Action that you drop into your deployment workflow. A minimal setup is two lines in your YAML. The action sends the version, commit SHA, environment, and changelog to Archyl on every successful deploy. It also supports custom fields—link to a specific system or container, set the status, include the author.

- uses: archyl/release-action@v1
  with:
    api-key: ${{ secrets.ARCHYL_API_KEY }}
    version: ${{ github.ref_name }}

That's it. Every tagged release now appears in your architecture workspace.

Webhooks — Configure a webhook endpoint in your project settings, then point GitHub or GitLab's release webhooks at it. When a new release is published or a tag is pushed, Archyl receives the event and creates a release entry automatically. You can set a tag pattern (e.g., v*) to filter which tags create releases, and assign a default environment so webhook-created releases land in the right place.

REST API — For teams using Jenkins, CircleCI, Bitbucket Pipelines, or any other CI/CD tool, the ingest endpoint accepts a simple JSON payload. Authenticate with an API key, send the version and metadata, and the release appears in Archyl. This is the universal escape hatch—if your tool can make an HTTP request, it can report releases.

All three methods are configured in the project settings under the Releases tab, with copyable code snippets and auto-populated API keys.

Environments

Not all deploys are equal. Pushing to staging is routine. Pushing to production is an event. Release Management tracks both, separately.

Environments are user-defined and color-coded. Create "Development", "Staging", "Production"—or whatever your team uses. Each release is tagged with its target environment, and you can filter the timeline to see only production deploys, or only what's in staging right now.

The environment model is flexible. A team running a single service might have two environments. A platform team managing forty microservices might have five. You define what makes sense for your project, and releases organize themselves accordingly.

The Timeline

The release timeline is the primary view. Releases are grouped by month, displayed in reverse chronological order, with version badges, environment tags, and status indicators. It's the answer to "what happened recently?"—at a glance.

Each release entry shows:

• Version — The semver tag or identifier (e.g., v2.4.0, 3.12.0-rc.2)
• Status — Deployed, In Progress, Planned, Failed, or Rolled Back
• Environment — Color-coded badge (Production, Staging, etc.)
• Linked element — The system or container this release belongs to
• Source — Where the release came from (GitHub Action, webhook, API, manual)
• Changelog — What changed, who authored it, signed-off-by info

Click any release to open its detail panel with the full changelog, dates (created, released, updated), impacted C4 elements, and a link back to the source (commit, GitHub release page, etc.).

The Deployment Matrix

For teams managing multiple services across multiple environments, we built a second view: the Deployment Matrix.

This is a grid where rows are your systems and containers, columns are your environments, and each cell shows the latest release deployed to that combination. At a glance, you can see that the Account API is on v3.1.0 in production but v3.2.0-beta in staging. Or that the Notification Service hasn't been deployed to production in three weeks.

The matrix makes environment drift visible. When staging and production versions diverge, you spot it immediately. When a service falls behind while others move forward, the gap is obvious.

Status Lifecycle

Releases aren't always clean. Deploys fail. Releases get rolled back. We track the full lifecycle:

• Planned — The release exists but hasn't been deployed yet. Useful for tracking upcoming versions.
• In Progress — Deployment is underway. Set automatically by CI/CD integrations during the deploy step.
• Deployed — The release is live in its target environment. The happy path.
• Failed — The deployment didn't succeed. The release entry stays as a record of what was attempted.
• Rolled Back — The release was deployed but subsequently reverted. This preserves the history—you can see that v2.3.1 was rolled back, when, and why.

Status transitions are automatic when using CI/CD integrations, or manual when creating releases through the UI.

Linking to Architecture Elements

Every release can be linked to a system, a container, or both. This is what gives releases architectural context.

In the project settings, you configure a default link target—the system and optionally a container where releases should be attached. The code snippets for GitHub Actions, webhooks, and the REST API update automatically to include the correct element IDs.

On the diagram, linked elements surface their release history in the detail panel. Right-click a container and you see not just its relationships and contracts, but its deployment timeline. This is where architecture documentation and operational reality converge.

Why This Matters

Architecture diagrams have always been a snapshot in time. They show you what the system is—the boxes, the arrows, the protocols. But they don't show you what the system is doing. Is that service on the latest version? When was the last deploy? Did someone roll back last Tuesday's release?

These are questions that come up in every architecture review, every incident response, every onboarding conversation. And until now, the answer was always "check the CI/CD tool" or "ask the team that owns it."

Release Management puts deployment history where it belongs: on the architecture itself. When someone asks "what version is the Payment Gateway running?", the answer is right there on the diagram—not in a different tool, not in a different tab, not in someone's head.

This is the same philosophy behind API Contracts and ADRs: architecture documentation should answer real questions that come up every day, not just describe structure in the abstract.

Getting Started

Navigate to your project's Settings and open the Releases tab. Choose your integration method—GitHub Action, webhooks, or REST API—and follow the setup guide. Create your environments, link a target system or container, and ship your first release.

From that point on, every deployment flows into your architecture workspace automatically. Your C4 diagrams stop being static blueprints and start being a living record of what's actually running.

Your architecture is more than structure. Now your tools reflect that.

Want to learn more about connecting your architecture to reality? See how API Contracts link your specs to the diagram, or how Architecture Change Requests bring pull request workflows to your C4 model.