How a Backstage Tech Radar plugin setup publishes your technology choices
Engineering teams need one place that shows which technologies are adopted, in trial, under assessment or on hold, and that page has to stay accurate as the landscape changes. A Tech Radar in Backstage answers that need by rendering your organization's decisions as a radar inside the portal. The Spotify Tech Radar plugin provides the rendering. It is a community-maintained plugin, not a core Backstage feature, so its package, repository and maintenance status are your responsibility to check. Before planning, confirm the current plugin package and its repository, and confirm that its release works with the Backstage version you run. The supported method is the plugin's documented configuration, and that documentation should be your starting point for installation.
The hard work sits outside the plugin. The radar only displays what your data source contains, so the first decision is where that data lives. Common options include a version-controlled file in a repository that the portal reads, or a structured data file that a platform team maintains. Each option has different consequences for who can propose a change, how changes are reviewed and how a stale entry is noticed. Ask who owns each ring assignment, how a technology moves from trial to adopted, and what happens to an entry whose owner has left. These questions matter more than the visual setup because an unmaintained radar looks authoritative while it quietly becomes wrong.
Keeping the radar current depends on a review process with a fixed cadence. Define a small group that approves changes, a written rule for each ring, and a schedule for reviewing entries that have not changed in a long time. Store the radar data under the same change control as other platform standards, so every movement has an author, a reviewer and a date in version history. Test the rendering after each Backstage upgrade, since plugin compatibility is a common source of breakage. The plugin is only one part of publishing your technology choices. The review process is what keeps the published radar trustworthy.
What a working Tech Radar setup needs before installation
The Tech Radar plugin sits on top of a running Backstage instance, so most of the setup work happens before anyone installs it. The cards below cover the platform, the version match, the data source, ownership and edit access that the radar depends on.
Running frontend and backend
The plugin adds a page to the Backstage frontend and reads its data through a backend plugin, so both halves of your app must build and start first. Confirm that your instance runs the frontend and backend packages you deploy, and that the backend can reach the location where radar data is stored. A radar added to a half-working portal will fail in ways that look like plugin bugs.
Matching Backstage version
Backstage moves all @backstage packages together, so a plugin release is tied to a specific Backstage line. Check the plugin's release notes for the Backstage versions it supports before you install, and pin the plugin to a version that matches yours. The current main line is shipped monthly and the next line weekly, so confirm which line your team tracks.
Chosen data source and location
Decide where radar entries live before you write any configuration: a file in a Git repository that the backend reads, or another source the plugin documentation supports. Confirm which format the plugin expects, how entries are identified, and whether the backend needs a read credential for that location. Keep the source in version control so every change to the radar has an author and a history.
Named owner group
Name a team that owns the radar and is accountable for its contents, such as a platform engineering or architecture group. In the catalog, that group should appear as an entity so the radar's owner is visible to every reader. Without a named owner, entries go stale because nobody is responsible for retiring technologies or moving them between rings.
Edit access for the team
Confirm that the owner group can change the radar source through a pull request and that reviewers outside the group can approve changes. Check whether your Git platform protects the branch and requires review, and whether the Backstage read credential can see the file without granting write access. Access should be separate from the portal's admin rights.
Review process and cadence
Agree on who approves a change, how often the radar is reviewed, and what triggers an entry to move or retire. This is a decision your organization makes, and the plugin does not make it for you. Write the process down before launch so the radar stays current after the first publication.
Configuring the radar plugin in sequence
This sequence takes the radar from a compatibility check to a published, reviewed page. Each step ends with a visible check so the team knows the plugin, the data and the review rule work before entries reach the portal.
Confirm plugin and Backstage compatibility
The platform engineer who owns the Backstage app checks the plugin's documented Backstage version support against the version your app runs, and confirms which Node.js release your deployment uses. Backstage supports two adjacent even-numbered Node.js releases, so confirm that your runtime is one of them before changing anything. Record the plugin version you intend to pin. The step is done when you have a written compatibility note that names the Backstage version, the Node.js version and the plugin version together.
Install the plugin packages
A developer adds the Tech Radar frontend package to the Backstage app and any backend package the chosen data source needs, then installs them with the repository's package manager so that the versions match the rest of the @backstage packages. Keep the install in a branch so the change can be reviewed like any other code change. The step is done when the app builds locally and the lockfile diff shows only the expected packages.
Register the radar route and navigation
The developer adds the radar page to the frontend routes and to the sidebar or navigation component, following the pattern the plugin documentation shows for the Backstage version in use. Decide early whether the page is visible to every signed-in user, since the radar will describe internal technology choices. The step is done when a local development build shows the menu entry, and selecting it opens an empty or placeholder radar without console errors.
Point the plugin at the radar data source
The platform team sets the configuration key that tells the plugin where radar data lives, whether that is a file in a repository, an API or another location the plugin supports. Confirm the exact key and accepted formats in the plugin's own documentation for your version. If the source is a private repository, the backend needs a read credential that is stored as a secret and not in the frontend. The step is done when the backend starts without configuration errors and the plugin reports that it loaded the data source.
Load a small test set of entries
Before loading the full catalog of technologies, the architecture or platform lead adds a handful of entries that cover each quadrant and each ring, and includes at least one entry that has moved since the last review. Keep the set short so mistakes are easy to spot. Fields such as name, quadrant, ring and description should follow the format the plugin expects. The step is done when a test entry you change in the source appears on the local radar after a reload, with the change visible in the right place.
Verify quadrants, rings and entry placement
The reviewer checks the rendered radar against the test set: each quadrant label, each ring label, the placement of every entry and the detail view that opens when an entry is selected. Compare the rendered output with the source file line by line, and confirm that the radar works for a signed-in user in your sign-in configuration. Record any mismatch as a defect before moving on. The step is done when every test entry renders in the expected quadrant and ring and no entry is missing or duplicated.
Add the review process to the source repository
The platform team adds a code owners file and a required review rule to the repository that holds the radar data, so changes to entries need approval from the people named as owners. Add a validation check that rejects entries missing required fields or using an unknown quadrant or ring, if your source format supports it. Confirm the owners and the set of required checks with the people who will maintain the radar. The step is done when a test change without an approval cannot merge, and a test change with a missing field fails the validation check.
Mapping radar entries to catalog and governance fields
This table maps each radar attribute to the catalog or governance field that supplies it and the rule that keeps it accurate. Read it as a checklist when you design your radar data model, since a value that has no owner or no review rule will drift out of date. The main takeaway is that owner, quadrant and ring should be tied to controlled sources, not free text typed into a file.
| Radar attribute | Source field | Rule that keeps it current |
|---|---|---|
| Entry name | Technology name in the radar data file, matched to a catalog entity name where one exists | Names come from the agreed list only; a new technology needs a review entry before it appears |
| Quadrant | A fixed set of quadrant labels defined by the platform team in the radar data | Values must come from the team's agreed vocabulary; reject any label outside that list in review |
| Ring | A fixed set of ring labels such as adopt, trial, assess or hold, defined by the governance group | Ring moves are recorded in the review log with a reason and the date of the decision |
| Description | Short text field in the radar entry, written in plain language for engineers | Reviewed at each cycle alongside the ring; stale descriptions are updated or flagged |
| Owner | A catalog Group or User reference, not a free-text name | Every entry names an accountable team; entries with no resolvable owner are held out of publication |
| Last reviewed date | Date field set by the review process when an entry is confirmed or changed | Set only by the reviewer at sign-off; entries past the agreed review interval are flagged for follow-up |
| Related catalog entity | Entity reference to the component, system or resource that uses the technology | Checked against the catalog so that retired or renamed entities do not leave orphaned radar entries |
Keeping the radar current through a review process
A radar goes stale for a predictable reason: an entry is placed in the Adopt or Trial ring when a team starts using it, and nobody is assigned to move it when the team stops. Over time the radar describes what was true two years ago. The fix is ownership. Name a group that owns the radar, usually an architecture or platform group, and make it responsible for every ring move. Before the first review, ask your governance owners how often technology decisions are normally revisited in your organization, and set the review cadence to match. Avoid copying a fixed schedule from another company, because the right rhythm depends on how fast your stack changes and how many people must sign off.
Give teams a proposal path so new technologies enter the radar through a defined route instead of appearing in a pull request nobody reviewed. A workable path has three parts: a short written proposal stating the problem, the alternatives considered and the team willing to run it, a review slot at the next cadence meeting, and a decision recorded with the ring and the reason. The same path should handle moves to Hold, where the decision is to stop starting new work with a technology. Teams that own the affected services should be consulted before a move, because they hold the operational knowledge the radar cannot show. Confirm with your governance owners who has authority to approve a move to Hold, since that decision often affects existing systems.
Record every change in the source history of the radar data so the reason for each move can be traced later. Require each change to reference the proposal or review note that approved it, and keep the review notes in the same repository or a linked location your auditors and engineers can read. Source history also shows how often entries move, which helps the group judge whether the cadence is too slow or too fast. Check that your Backstage deployment reflects merged changes after each review, and confirm with the plugin's maintainers how the radar data is loaded and refreshed in your version, since that determines when a reviewed change becomes visible to developers.
Choosing where the radar data lives
One platform team owns the radar, edits its contents and publishes it on its own schedule. This is the simplest arrangement because there is one editorial voice and few handoffs. Changes usually move through a pull request to the repository that holds the radar data, so the commit history also serves as a record of who changed each entry and why.
- Write path: An editor changes the data file or source the plugin reads, normally through a pull request reviewed by a second member of the team.
- Approval: A named owner, supported by a small rota of reviewers, decides which technologies move between rings or quadrants.
- Drift risk: Low while the team is small, but entries go stale when the team is busy and no one outside it notices. Record a review date on every entry.
- Scale limit: Every new technology depends on one team's capacity, so backlogs grow as the number of product groups grows.
Before committing to this model, confirm in the plugin's documentation which data sources it reads (files, URLs or other backends) and whether a change appears without a rebuild or redeploy.
Several groups propose entries, and a central steward or small council approves them. This suits organizations where payments, data, and mobile teams each adopt different tools and need a say in what the company recommends. The main design work is deciding how proposals enter the system and who resolves conflicts between groups.
- Write path: Each group submits proposals, typically as pull requests against the shared data or through a request process the platform team runs.
- Approval: A steward per quadrant or per group reviews proposals, with a council resolving disagreements about ring placement.
- Drift risk: Higher than in a single-team model. Groups may add the same technology under different names, leave proposals open for months, or move an entry without telling others.
- Ownership metadata: Record which group proposed each entry so that questions go to the right people.
Before committing to this model, confirm whether the plugin accepts data from more than one source or whether all proposals must be merged into one file before the radar displays them, and whether the data format can carry ownership fields.
Some organizations already record technology decisions in an architecture repository, a decision log, a governance tool or a wiki. In this model, that system is the source of truth, and the radar is a published view of it. The risk to manage is a second copy that nobody updates.
- Write path: Decisions are made in the existing register, then exported or synchronized into the radar's data. Manual copying works for a small list but invites errors.
- Approval: Approvals stay in the existing process, so the radar needs no separate sign-off step.
- Drift risk: The radar and the register disagree after one is updated and the other is not. A scheduled import reduces this risk but does not remove it.
- Field mapping: Check that the register records the fields the radar needs, such as quadrant, ring, a short description and the date of the last decision.
Before committing to this model, confirm whether the plugin can read from the register's export format or API, how the import job authenticates, and whether the job can run on a schedule that your review cycle requires.
Securing the radar source, the plugin and the review trail
The radar is only as trustworthy as the process that changes it. These cards cover who can edit the radar data, who can see it, where credentials sit, which code runs inside the portal and how each ring change is recorded. Confirm each control in your own environment before the radar goes live.
Restrict write access to the radar source
The radar data usually lives in a Git repository that the portal reads. Anyone who can merge to its default branch can move a technology from Adopt to Hold, and the portal will display that change to every engineer. Protect the default branch, require pull requests, and require approval from named reviewers such as the architecture or platform group. Confirm that the branch protection rules apply to administrators as well, so no one can bypass review.
Govern radar data with portal access rules
Radar entries can reveal internal decisions, such as a vendor being phased out or a contract being reviewed. Treat the radar as organizational information, not a public page. Confirm that the sign-in provider and any authorization policy in your Backstage instance limit who can open the radar page, and that guest access is off in production. Check that the same rules apply when someone reaches the data through the API or search.
Keep private source credentials on the backend
If the radar file sits in a private repository, the portal needs a read credential to fetch it. That credential must be configured in the backend, not in frontend code, because anything the browser loads can be read by a user. Use a token scoped to read only the radar repository, store it in your secrets system, and confirm that it does not appear in the built frontend bundle or in browser network responses.
Vet plugins because they run unsandboxed
Backstage plugins run as code inside the portal process, and the framework does not sandbox them. A radar plugin with a bad dependency could read backend configuration, including tokens for other integrations. Before installing the Spotify Tech Radar plugin, review its maintainer, release history and the packages it pulls in, and pin the version. Confirm the plugin's required configuration keys and check that it requests only read access to the radar data.
Record who approved each ring change
When a ring change is questioned later, the team needs to show who proposed it, who approved it and when it went live. Git history and pull request approvals provide that record if you keep them. Confirm that merge commits are retained, that reviewers' approvals are recorded in the platform, and that the radar's history can be exported for an internal review. Decide the retention period with your records team.
Common Tech Radar failures and how to fix them
This table lists the symptoms teams most often report with an internal Tech Radar in Backstage, with the likely cause, the check to run and the fix for each. Work down the rows in order, because registration and data path problems produce several of the other symptoms. Confirm exact error messages against the Tech Radar plugin's own documentation before acting on them.
| Symptom | Likely cause | Check to run | Fix |
|---|---|---|---|
| Radar page does not appear in navigation | The frontend plugin is not registered in the app, or the sidebar item was never added to the app's navigation component | Confirm the plugin package is listed in the frontend app dependencies and that the app's routes and sidebar include the radar page, then reload the app after a clean build | Add the plugin's page and sidebar item to the app, rebuild the frontend, and redeploy. Confirm the setup steps in the plugin's README for the current wiring |
| Radar page loads but shows an error or blank screen | The radar data source URL points to a missing file, or the frontend cannot reach the backend route that serves the data | Open the browser network tab and check the request for the radar data, then confirm the response status and the file path configured for the plugin | Correct the data source path in the plugin configuration, confirm the file is published in the location the configuration expects, and check the proxy or backend route for access |
| Empty radar after a valid change was merged | The data file in the source repository is not the one the portal reads, or the deployed portal has not picked up the latest commit | Compare the configured source location with the file you edited, and check the deployed image or build date against the merge | Point the configuration at the correct file or branch, then redeploy so the portal rebuilds with the updated data. Confirm caching behavior with your deployment setup |
| Entries missing from one ring | The entry uses a ring name that does not match the configured rings, or a required field such as the quadrant or description is missing or misspelled | Validate the data file against the schema the plugin expects, and compare ring and quadrant names character by character with the configuration | Correct the ring or quadrant value to a configured name, fill in required fields, and add a validation step to the review workflow so malformed entries fail before merge |
| Build fails after a Backstage upgrade | The Tech Radar plugin version does not match the other @backstage packages, or the plugin's API changed in the new release line | Check the installed versions of the plugin and the core @backstage packages, and review the plugin's release notes and the Backstage Upgrade Helper for the target version | Bump the plugin with the other Backstage packages using the standard version bump command, update any changed imports or configuration keys, and rerun the build before deploying |
| Radar changes merged without review | No branch protection or required reviewer rule covers the directory that holds the radar data, or the review owner is not defined | Check the repository's branch protection settings and code owners file for the radar data path, and review recent merges to that path | Require review from the named radar owners for changes to the data path, restrict direct pushes to the default branch, and record the approval step in the radar's governance notes |
| Radar shows entries that no longer reflect the decision | Entries were not moved or retired after a review, so the data file has drifted from the agreed state | Compare the file with the latest approved decision record or meeting notes, and list entries with no change in the last review cycle | Schedule a review that moves, retires or confirms each entry, and make the review outcome the source for the next data change |
| Users see a radar they should not access | The radar page or data route does not apply the access rules used for the rest of the portal, or guest access is enabled in production | Sign in with a user outside the intended group and request the radar page and data route directly, then review the sign-in and permission configuration | Apply the portal's access policy to the radar route, disable guest access in production, and confirm the result with a test user before publishing the link |
Questions teams ask before setting up a Tech Radar in Backstage
What does a Backstage Tech Radar setup cost, and what drives the effort?
The cost is mostly the effort to design and build the radar data flow, and it depends on how many sources feed the radar, how the review works, and which Backstage version you run. Each additional data source, such as a spreadsheet, a Git repository or a survey export, adds a parser, a validation step and an owner to maintain it. A lightweight review model with one approver costs far less to run than a model with a architecture board, a sign-off chain and published decision records. Your Backstage version matters because the plugin must match the @backstage packages you already run, so an older app may need dependency work first. Ask any partner for a written scope that lists each data source, each review step and the Backstage version, with a separate line for the one-time build and the ongoing review effort.
How long does it take to publish a Tech Radar in Backstage?
Duration is set by the number of data sources, how many decisions must be agreed before the first publish, and how much of your Backstage setup already exists. A single source with an agreed set of rings and quadrants is the fastest path. Delays usually come from debating categories, waiting for reviewers, and fixing an app that is behind on upgrades. Ask for a schedule with milestones for agreeing the ring and quadrant model, building the data path, the first review cycle and the handover, and confirm which of those depend on your team's availability.
What does the client need to provide for a Tech Radar project?
You need three things before work starts: a named owner who can make decisions about the radar, a source repository where the radar data and its review history live, and a group of reviewers who agree to meet on a fixed cadence. The owner resolves disputes about what belongs on the radar. The repository gives you version history, pull request review and a clear audit trail for each change. Reviewers, usually from architecture, security and platform engineering, approve moves between rings. Also confirm access to your Backstage instance, the identity provider used for sign-in, and who can merge changes to the data.
Can our own team set up a Tech Radar in Backstage without outside help?
Yes, a team already running Backstage can install and configure the Spotify Tech Radar plugin, provided it has someone comfortable with TypeScript, the Backstage plugin system and its configuration files. The harder part is usually the governance: agreeing what the rings mean, who approves moves and how entries are retired. Outside help is most useful for the design of the data path and the review process, and for a first publish that your team can run without a partner. Before deciding, check the team's capacity to maintain the plugin through Backstage upgrades, since the plugin must track the same release line as the rest of the portal. Plan for the same skills whether you build it internally or with a partner.
How do we keep a Tech Radar from going stale?
A radar goes stale when no one owns the review calendar, so set a fixed review cadence and a named owner for each quadrant before launch. Treat each change as a pull request, so reviewers see proposed moves and their reasons in one place. Add an expiry rule for entries, so that any item not reviewed within an agreed period is flagged for a decision. Track the last review date for each entry and show it on the radar page, so readers can judge how current a recommendation is. Ask any partner to describe how the review cadence will be handed over and how the team will be trained to run it.
How does a Tech Radar relate to catalog ownership and scorecards?
The radar describes technologies the organization recommends, while the catalog records which components use them and who owns those components. Linking the two lets a team see which services run on technologies that are being phased out. Scorecards can then check whether a service uses only technologies from an approved ring, but they depend on accurate ownership data in the catalog. Keep the radar entries as a fixed vocabulary, such as a set of names matching the technologies recorded in component metadata, so matching is reliable. Before you build the link, ask for a written mapping of radar entries to catalog fields and confirm how each team will keep its component metadata current.
How DeployOpen scopes and supports a Backstage Tech Radar
DeployOpen approaches the Backstage Tech Radar plugin as a scoped piece of work inside your own Backstage deployment, which we plan, build, test and document in your environment. Engagements are fixed-scope, so the radar data sources, review process, deliverables and timelines are agreed in writing before the work starts.
How we scope
- Confirm which technology categories and rings your organization wants the radar to show, and who owns each category.
- Document where radar data will come from, such as a maintained YAML or JSON file in a Git repository or an internal data source.
- Agree the review cadence, the approvers for ring changes and the entries that will be published at launch.
- Set out the written scope, deliverables and timeline, with ongoing support available as a retainer after handover.
How we build
- Install and configure the Spotify Tech Radar plugin against your Backstage version, with the data source connected to the portal.
- Model radar entries, rings and quadrants so they match your agreed categories and render correctly for your readers.
- Test the radar in a non-production environment, including how entries load, how links resolve and how the page behaves for signed-in users.
- Document the data format, the contribution steps and the build and deployment process so your team can maintain the radar.
How we hand over
- Deliver the radar configuration, data files and review checklist to your repository with an agreed ownership model.
- Walk your platform and architecture team through the contribution workflow, including how proposals are submitted and approved.
- Provide written runbooks covering routine updates, rollback of a bad data change and how the plugin version is kept current.
- Record decisions on categories, ring definitions and approvers so future reviewers understand why the radar looks as it does.
How we support
- Provide ongoing support and upgrades for the radar plugin as a retainer, aligned with your Backstage upgrade schedule.
- Review plugin compatibility with new Backstage releases before your upgrade so radar pages do not break unexpectedly.
- Support periodic radar reviews by preparing change summaries that your architecture board can approve quickly.
- Confirm with your team which plugin maintenance and security checks belong in the retainer and which stay in-house.
