Self-service is a documentation problem

A platform team can build a genuinely self-service deployment path and still find that most changes arrive as a request in a channel. That was true for us for longer than it should have been, and the gap wasn’t technical.

What we built

An ArgoCD-based path: application definitions living in Git, Helm charts as the packaging unit, and a repo structure that let a team own their values and promote between environments with a pull request. Platform owned the cluster, the App-of-Apps / ApplicationSet layer, and the shared chart conventions. Developers owned the service manifests and the merge that moved them.

On paper that is self-service. In practice, for months, people still asked us to “just deploy it.”

Why it didn’t get used

Three reasons, none of which were “ArgoCD is hard”:

Discoverability. The path existed in a repo. The ticket queue existed in Slack. People default to the interface that answers them.

Fear of breaking production. Without a written rollback and a clear “what happens when I merge,” a PR feels riskier than asking someone who has done it before.

Unclear ownership of the escape hatch. When something fell outside the paved road — a one-off Job, a non-Helm artifact, a shared resource — nobody knew whether to extend the pattern or open a ticket. Ambiguity sends people back to the channel.

What changed adoption

We wrote the paved road down as a short runbook: how to add an app, how to promote, what to do when sync fails, and when to stop and ask. Then we ran a session with the teams that still opened the most tickets, walking through a real change end to end.

The tooling did not change much. The number of “can you deploy this?” messages did. The runbook mattered more than another ApplicationSet feature.

The measure I’d use now

Ticket volume to the platform channel is a tempting metric and a bad one — it rewards being unreachable. Better signals:

• Ratio of production changes that arrive as PRs to the GitOps repo versus manual syncs or platform-authored commits.
• Time from “ready to deploy” to “live,” measured for teams that are not on the platform team.
• How often the escape hatch is used, and whether those uses get folded back into the paved road.

Self-service is working when people who have never spoken to you can ship, and when the exceptions shrink over time instead of becoming folklore.