Portals, CLIs or Git: what developers really use

When platform teams show off their work, they usually show a portal. Nice cards, service pages, a big "Create" button. It demos beautifully.

But when I watch developers actually work, they rarely live in a portal. They live in their editor, their terminal, their pull requests and their chat tool. So the question every platform team should ask is: where should the platform meet developers?

Three ways to offer a platform

A web portal (Backstage, Port and others). Great for discovery: finding services, owners, docs, and for occasional tasks like creating a new service. Less great for things you do twenty times a day.

A CLI. Developers who live in the terminal love a good command-line tool. platform create service, platform logs, platform env up. Fast, scriptable, easy to use in CI. The downside: someone has to build and maintain it, and it needs to be installed and updated everywhere.

Git as the interface (GitOps). Developers change a YAML file in a repository, open a pull request, and automation does the rest. Every change is reviewed, versioned and auditable. The downside: YAML fatigue, and less discoverable for newcomers.

None of these is "the right one". They're good at different moments.

The best platform interface is the one developers are already looking at when they need it.

What I've learned from asking developers

When you ask developers what they want from a platform, the answers are rarely "a nicer portal". More often they're things like:

• "I just want to know why my deployment failed without asking someone."
• "I want logs for my service without learning a query language."
• "I want a test environment without opening a ticket."
• "I want to know who owns the service that's breaking mine."

Notice that these are about outcomes, not interfaces. The platform team's job is to make those outcomes easy, wherever the developer happens to be.

Some practical patterns that work well:

• Bring information to the pull request. Preview URLs, test results, security findings and cost changes as comments on the PR.
• Bring alerts to chat with links straight to the right dashboard and runbook.
• Use the portal for discovery and rare actions, not daily work.
• Keep the real source of truth in Git, and let the portal and CLI read from it.

Docs are a feature

The most underrated part of any platform is documentation. A platform nobody understands is a platform nobody uses.

Good platform docs:

• Start with "how do I do X" guides, not architecture diagrams.
• Live next to the code (docs-as-code) and are reviewed like code.
• Have copy-paste examples that actually work.
• Are owned by someone and reviewed regularly.

If you only have time for one improvement this quarter, improving docs often beats adding a new feature.

Before and after numbers

Whatever interface you choose, measure whether it helps. Useful before and after comparisons:

• Time from "I need a new service" to "it runs in a test environment".
• Number of routine requests to the platform team.
• How often developers need help to debug a failed deployment.
• Survey answers to "how easy is it to ship a change?"

If the numbers don't move after launching a portal, the portal isn't the problem you needed to solve.

So, which one should you build?

Start where your developers already are. For most teams, that's Git and pull requests, with good automation behind them. Add a CLI if your developers are terminal-heavy. Add a portal when discovery becomes a real problem, usually once you have dozens of services and teams.

My take: build the platform around developers' habits, not around the demo. The demo lasts ten minutes, the habits last years.

— Desly