Why third-party Backstage plugins need a review before install
A platform team wants a plugin that shows CI status, open incidents or cloud cost on entity pages, and must decide whether to install it. Backstage itself carries no license fee and no paid edition from the project, since it is an Apache-2.0 framework. That means the risk you carry comes from the plugin: who maintains it, which repository it comes from, how often it is released, and what it is allowed to reach. Those are the signals your team controls, so the decision should be made deliberately rather than by copying a plugin from a blog post or a demo.
A plugin runs inside the portal's backend and can use whatever tokens, connection settings and catalog data that backend already holds. A plugin for a build server, for example, may need an API token with read access to job history, and a careless configuration can let it read far more than the entity page needs. The review should therefore answer three questions before anything is installed: which credentials the plugin asks for, what scope each credential has in the source system, and which catalog entities and annotations it will read. Confirm these against the plugin's own documentation and a test instance, not only the README.
This section is followed by the checklist, a comparison of plugin sources, and the steps for a trial installation in a non-production instance. One timing point matters for the plan: the Backstage versioning policy says high and critical severity vulnerabilities are backported to releases from the last 6 months where feasible, and other security fixes may be backported. Community plugins do not inherit that policy. Ask each plugin maintainer how fixes are released and how quickly, and check that your Backstage version is one the plugin supports. The Backstage release and versioning policy sets out the release lines you will need to track.
Six checks to complete before a third-party Backstage plugin enters your portal
Each card is a check you can run in parallel before approving a plugin. Together they answer who stands behind the code, where it is maintained, whether it tracks the Backstage release line you run, what it can reach, which secrets it holds, and how it will survive the next upgrade.
Maintainer identity and accountability
Identify who publishes the package and who answers issues and security reports. Look for named maintainers tied to a company or an active community, a published security contact, and a clear owner for the package on the registry. Ask whether the maintainer is paid to maintain it or whether it depends on one volunteer. A weak answer is an anonymous author, a single unreachable maintainer, or no way to report a vulnerability before disclosure.
Repository and publishing origin
Confirm whether the plugin lives in the community-plugins repository, a vendor repository, or a personal fork. Check that the npm package name and version match the source repository and that the publisher is the same party that owns the code. Treat a plugin whose repository has moved, or whose package points to a repository you cannot find, as unverified. A weak answer is a package published from an unlinked repository.
Release activity and target release line
Read the release history and the Backstage version range the plugin declares as a peer dependency. Confirm it targets the main release line you run, not only the next line, and that it has shipped fixes for recent Backstage versions. Check whether the project publishes a changelog and whether security fixes are announced. A weak answer is a plugin that declares support for a release line you have not adopted or has no release notes for recent changes.
Permissions and API scopes requested
Review every permission the plugin asks for, including the scopes on any token it needs from a source system such as a CI server, issue tracker or cloud account. Compare the requested scopes with what the feature actually displays. Prefer read-only scopes and ask whether write actions such as re-running jobs can be disabled. A weak answer is a plugin that asks for administrator scopes to display a status badge.
Credentials and where they are stored
Map each credential the plugin needs to the layer where it runs: backend configuration, a secret store, or the browser. Confirm that tokens are read by the backend, injected from your secret manager, and never placed in frontend bundles or entity annotations. Ask who issues the token, how long it lives, and how you rotate it. A weak answer is a plugin that expects a token in app-config files committed to source control or exposed in the browser.
Upgrade path at the next version bump
Plan for the day the Backstage version moves. Check whether the plugin's dependencies are pinned to the @backstage packages you run, whether the maintainer documents migration steps, and whether you can test the plugin in a staging portal before production. Record the plugin's version and owner in your catalog so the upgrade has a named contact. A weak answer is a plugin with no tested upgrade notes that forces you to stay on an old release line.
Why Backstage plugins run unsandboxed and what that means for your review
A Backstage plugin is code that runs inside your portal, with the same access as the portal itself. Backend and frontend plugins are JavaScript packages loaded into the same Node.js process as the rest of Backstage. Nothing isolates them the way a browser extension is isolated from a web page, so a plugin that reads a token, opens a network connection or registers a route has whatever reach the host process has. Your review therefore has to cover where the code came from, which dependencies it pulls in, and which configuration values it reads, not only the features its README advertises. Confirm the current isolation model in the Backstage documentation before you rely on any statement about it here, because the project's guidance on plugin trust may change between releases.
The practical consequences fall on sign-in and secrets. A backend plugin can read entries from app-config.yaml, including values that were meant for another plugin, and it can call APIs with any credential it is given. Ask each candidate for the exact configuration keys it reads, the environment variables it expects and the scopes of every token it asks for, then check that each one is stored as a secret and not in the repository. Find out whether the plugin needs its own backend credentials or can work through an existing proxy, since a shared credential widens the blast radius of a bad release.
Sign-in matters most when a new plugin adds routes. The Backstage authentication documentation advises configuring sign-in resolvers so every provider resolves to the same identity, and not offering guest access in production. A plugin that exposes a new API path can be reached by anyone who can reach the backend, and if guest access is still enabled or the resolver maps a login to a different user, the route may run under an identity you did not intend. Before installing, test the plugin's new endpoints with an unauthenticated request, a signed-in user without the right group, and a guest session, and record the result as part of the approval.
Which plugin source fits which level of risk
This table compares four sources of Backstage plugins by typical maintenance owner, review effort, upgrade responsibility and the situations where each fits. Read each row against the risk level of the data and credentials the plugin will touch, not only the feature it offers. Whatever the source, confirm maintainer activity and release history for each named plugin yourself before installing it.
| Plugin source | Typical maintenance owner | Review effort and upgrade responsibility | Where it fits |
|---|---|---|---|
| Community-plugins repository | Individual or volunteer maintainers listed in the repository, with no guaranteed support from the Backstage project | Full review of code, dependencies and requested credentials before install. Your team owns upgrades and must retest after each Backstage version bump. | Read-only views for low-sensitivity data, pilots, and integrations where a second source is not available |
| Vendor-maintained repository | The vendor that operates the connected tool, under its own release and support terms | Review the vendor's release notes, token scopes and dependencies. Upgrades depend on the vendor keeping pace with Backstage, so confirm compatibility with your version. | Integrations with a tool your organization already licenses and supports, where the vendor's accountability matters to auditors |
| Internal plugin built by your team | Your platform or portal team, which owns code, dependencies and on-call support | Highest build effort, but the review is your own code review. Your team carries every Backstage upgrade and security patch for the plugin. | Connections to internal systems no public plugin covers, or where the plugin must handle sensitive data under your own controls |
| Fork of an upstream plugin | Your team for the fork, while the upstream project keeps its own release line | Review each upstream change before merging into the fork. Your team owns security fixes, rebasing and compatibility, which grows with every divergence from upstream. | A proven upstream plugin needs a change the maintainers will not accept, and your team accepts ongoing merge work |
| Plugin with a shared or user-level credential | Depends on the source above, but the credential owner carries the access risk | Confirm the token scope, storage location and rotation process before install. Review effort rises when the plugin reads secrets or can trigger builds or changes. | Read-only status views where the credential is scoped narrowly and kept out of the browser |
| Plugin that runs unsandboxed in the backend | Same owner as the source, but the code runs inside your Backstage process | Treat any backend plugin as trusted code with access to your configuration and secrets. Review its dependencies and version pins on every upgrade. | Only where the source review is complete and the plugin's access matches its purpose |
| Plugin that has moved or been archived | Unclear, so confirm the current owner before installing | Check the repository's archive status, last commit and open security issues. Plan a migration or replacement before the next Backstage upgrade. | Generally not a fit for new installations. Keep only for existing deployments with a dated replacement plan |
How deep the review goes for each kind of plugin
A frontend-only plugin runs in the browser and renders data it receives from the Backstage backend or from an existing API. It holds no secret of its own, so the review concentrates on what the page can reach and what it displays. Confirm that the plugin does not call external services directly with embedded keys, and that any data it shows is already filtered by the permissions your sign-in model applies.
- Bundled code: Read the package's dependencies and check whether it pulls in scripts or assets from third-party domains at runtime.
- Data source: Identify which backend route or proxy endpoint supplies the data, and confirm that route is covered by your authorization policy.
- Rendered content: Check how the plugin handles untrusted text from catalog annotations or external systems, so that it cannot inject markup into entity pages.
- Configuration exposure: Verify that no token, URL with credentials or internal hostname is shipped in the frontend configuration.
- Update path: Note who tracks new releases and whether the package version is pinned in your lockfile.
Record the package version, the dependency list, the network calls observed in a browser session, and the reviewer's name before approval.
A backend plugin that reads from an external system holds a credential and makes requests on behalf of the portal. This is the role where most exposure sits, because the token usually grants access wider than any single user. Review the routes it adds, the scopes the token carries, and whether it forwards requests to the external system without checking who asked.
- Exposed routes: List every route the backend plugin registers, and confirm which ones are reachable by guests, by signed-in users or only by other backend plugins.
- Token scope: Ask for the smallest read-only scope that serves the use case, and confirm the credential cannot list or read resources outside the teams it is meant to show.
- Proxying: Determine whether the plugin proxies arbitrary paths or fixed endpoints, since open proxies let callers reach any API the token can access.
- Storage and rotation: Confirm the token is read from your secret store, is absent from logs and the frontend, and has a rotation owner.
- Approval: Name the security reviewer and the platform owner who must both sign off before the credential is issued.
Record the requested scopes, the route list with auth requirements, a test showing an unauthorized user is refused, and the rotation date owner.
A plugin that writes to or triggers actions in an external system can change production state, such as rerunning a pipeline, acknowledging an incident or altering a configuration. It deserves the deepest review because a flaw can turn a catalog page into an action channel. Treat it as a privileged integration, with explicit approval for each action type it exposes and a clear record of who initiated each change.
- Action inventory: List each write or trigger operation, its target system and its blast radius, and remove any operation you do not need.
- User identity: Check whether actions run under the signed-in user's own OAuth token or under a shared service credential, since shared credentials remove attribution.
- Confirmation and audit: Confirm the plugin requires an explicit user action, logs who triggered what and in which system, and that those logs reach your audit store.
- Input handling: Verify that parameters from the portal are validated before they reach the external API, to avoid injection into downstream calls.
- Change control: Require the same approval for enabling a new action as for issuing a new credential, and document who may change it later.
Record the action inventory, the identity model for each action, a test showing one action produces an audit entry, and the approval from the owner of the target system.
Plugins published by a vendor or maintained by a commercial company are often the strongest candidates for production, but they still need review. The question shifts from whether the code is maintained to whether the vendor's support terms, release process and repository location meet your change-control needs. Confirm where the package is published and whether the vendor's repository is the one you will track.
- Source location: Confirm whether the package comes from the vendor's own repository or from a community collection, and record the exact repository URL.
- Release discipline: Check the vendor's changelog and how it versions breaking changes against Backstage releases.
- Support boundary: Ask what the vendor supports, what falls to your team, and how security fixes are delivered.
- Licensing: Confirm the license of the plugin and of any paid module it requires, since some vendor plugins depend on commercial components.
- Dependency on other plugins: Note any required Kubernetes or proxy plugins, because their configuration becomes part of this plugin's trust boundary.
Record the repository URL, the license, the support statement in writing and the reviewer's notes on which role this plugin plays in the tabs above.
How to run a plugin trial before production
This sequence moves a candidate plugin from a compatibility check to a recorded approval in a non-production instance, so the team knows what the plugin reads, what it can change, and how to back it out before it touches the production portal.
Confirm compatibility with your release line
Start by checking the plugin's documented Backstage compatibility against the release line your instance runs, and note the Node.js version the plugin expects. Your Backstage instance supports exactly two adjacent even-numbered Node.js releases, so confirm the plugin works with one of them. Use the upgrade guide to keep your @backstage packages aligned with the plugin's peer requirements rather than adjusting versions ad hoc. The step is complete when you have a written note naming the Backstage version, the Node.js version and the plugin release you tested against.
Install in a pinned non-production instance
Install the plugin in a non-production Backstage instance that uses the same @backstage package versions as production. Pin the plugin to a specific release rather than a floating range, and confirm that the install does not pull in a second copy of any @backstage package. The step is complete when the instance builds, starts and shows no new errors in its backend logs after startup.
Configure with a read-only test credential
Create a credential that can only read from the source system, scoped to one test project or namespace. Store it in your secrets mechanism and reference it from the plugin configuration, keeping it out of frontend configuration and version control. The step is complete when the plugin loads data for the test project and a request outside that scope is refused by the source system.
Verify annotations and displayed data
Add the entity annotations the plugin requires to a few test catalog entities, then compare what the plugin shows with the same data in the source system. Check counts, statuses, timestamps and links, and confirm that entities without annotations show an empty state rather than another entity's data. The step is complete when a reviewer has signed off on a short table of matched and mismatched fields.
Review dependency and lockfile changes
Compare the lockfile before and after the install and list every new or upgraded package the plugin brings in, including transitive dependencies. Check each new package's maintainer, license and recent activity, and flag any that run install scripts or make outbound network calls at build time. The step is complete when the list is attached to the review record and each flagged package has a documented decision.
Record approval and rollback steps
Write down who approved the plugin, the release and commit tested, the credentials it uses and where they are stored, and the exact steps to remove it, including the configuration keys and catalog annotations to delete. Test the rollback in the non-production instance and confirm the portal still starts without the plugin. The step is complete when the record is filed and the rollback has been run successfully once.
Credentials and permissions to scope before a plugin goes live
A third-party plugin inherits whatever access you give it, and most plugins run inside the Backstage backend with the same trust as your own code. The five checks below cover what the plugin can read, where its secrets live, whose identity it acts as, who can reach its routes, and how its activity is traced.
Scope the external API token
Create a token for the plugin that can only read the data the portal displays, and limit it to named projects, pipelines, or workspaces where the vendor supports that. Ask whether the plugin ever writes back to the source system, and if it does not need to, confirm that the token has no write scopes. Record the scopes in your plugin review so a later token rotation does not quietly widen them. Confirm the token key names in the plugin's own configuration documentation.
Keep tokens out of frontend bundles
Plugin credentials belong in backend configuration, loaded from environment variables or a secrets store, and never in values that the frontend reads. Anything exposed in a frontend bundle can be read by every signed-in user through the browser. Check each plugin's frontend and backend packages to see which one needs the secret, and confirm that the proxy or backend plugin is the only path that calls the external API.
Choose per-user or shared credentials
Where a plugin supports per-user OAuth or personal tokens, it can act with each user's own permissions, so it cannot show or trigger more than that user could in the source system. Where it only supports a shared service credential, every portal user gets the same access, so the credential needs the narrowest scope and an owner who can rotate it. Decide this per plugin and write the decision down, since some plugins offer both modes and the default may not be the one you want.
Restrict access through sign-in resolvers
Plugin routes inherit the portal's sign-in, so the resolver that maps each identity to a catalog user decides who can reach them. Follow the authentication guidance to make every provider resolve to one identity model and to turn off guest access in production. Then test with a user from each group that should be excluded, because a plugin that only checks for a signed-in user lets any authenticated account through.
Review plugin activity in source systems
Ask the vendor or project which API calls the plugin makes and how they appear in the audit logs of the source system. Route those logs to your central store, and set alerts for token use from unexpected hosts or for bursts of reads on projects outside scope. Review the logs on a schedule that matches your change process, and treat any new plugin version as a change that needs the same review as the first install.
Questions teams ask before approving a third-party Backstage plugin
How much internal effort does a plugin review take?
The effort depends on how many plugins you are reviewing, how many external systems each one touches, and how deeply you examine the credentials each plugin needs. A single read-only plugin that calls one API with a scoped token is a short review. A plugin that writes to a delivery or incident system, or that asks for broad organization-wide tokens, needs more time for the source read, the permission mapping and the test in a non-production instance. Plan the review per plugin, then multiply by the number of systems. Ask any partner to price the review by plugin count and credential depth, and to state what is one-time (the first review) and what recurs (re-review after major upgrades or maintainer changes).
Can our own team run the plugin review without outside help?
Yes, if you have people who can read the plugin source, understand the target system's token and permission model, and run Backstage in a test environment. The team usually needs a Node.js and TypeScript reader, someone who knows the identity and access model of each external system (such as which API scopes a token needs), and a security reviewer who can judge secret handling. Check the plugin's repository, its release history and its open issues yourself, and record the answers in a short review note per plugin. Bring in outside help when the review covers many systems at once or when you need written evidence for an assessment.
How long should a plugin trial run, and what sets its length?
Trial length is set by the questions you need answered, not by the calendar. A trial should exercise the plugin against a non-production instance of the external system, confirm that it reads only what the entity page needs, check that credentials stay on the backend, and confirm the plugin still works after a Backstage version bump in a staging copy. Longer trials are needed when the external system has many projects or teams to map, or when your change process requires a full cycle of releases to observe behavior. Agree on the trial's exit criteria before it starts so the length follows from them.
What should a written quote for outside plugin review include?
A useful quote states what is in scope and what is not, so you can compare offers. Ask for the following in writing:
- The list of plugins and the external systems each one connects to
- The environments where testing happens (for example, a staging Backstage and a non-production instance of each system)
- The credentials and token scopes reviewed, and where each one is stored
- The written acceptance criteria that mark the review as complete
- Who fixes issues found, and whether that work is priced separately
- The deliverables, such as a review note per plugin and a configuration record
DeployOpen agrees scope, deliverables and timelines in writing before work starts, so a quote follows from that written scope.
Who owns upgrades when a plugin falls behind a Backstage release?
Your organization owns the decision, and the plugin's maintainer usually owns the code change. Backstage moves its @backstage packages together with yarn backstage-cli versions:bump, and the Backstage Upgrade Helper shows template changes between versions. A community or vendor plugin may lag that cycle, so you need an agreed rule: pin the last compatible version, delay the Backstage bump, or fork and maintain the patch yourself. Name an owner for each plugin in your catalog, state who tests it after each bump, and decide in advance how long a lagging plugin may stay on the older Backstage line. Ask any partner who will carry that upgrade work and whether it is in the retainer or a separate fixed-scope job.
What should we do when a plugin is abandoned by its maintainer?
Treat abandonment as a risk with a defined response, not a surprise. Check the plugin's release activity, open security issues and maintainer responses before you rely on it, and set a rule for when a plugin counts as inactive. When one goes quiet, your options are to replace it with a maintained alternative, to remove the entity page feature, or to take over maintenance through a fork with a named owner. Keep the plugin's credentials scoped so an unmaintained plugin cannot reach more than it needs. Record the decision in your catalog so the owner and the review date are visible to other teams.
Why do Backstage plugins run unsandboxed, and what does that mean for review?
Backstage plugins are code that runs inside the Backstage frontend or backend process, so they have the same access to the process as Backstage itself. The framework does not isolate a plugin in a separate sandbox, which means a plugin can read any configuration or secret the backend can read, and can call any network address the backend can reach. For that reason, review each plugin's source as you would any dependency with production access. Check which configuration keys it reads, which tokens it requests, which outbound hosts it calls and whether it exposes data to the browser. Limit the secrets available to the backend, and give each plugin its own narrowly scoped token.
Where should we check whether a plugin is community-maintained or from a vendor?
Start with where the plugin is published and who signs its releases. Plugins in the community-plugins repository are maintained by contributors and have their own review standards, while vendor plugins are maintained in the vendor's repository and usually follow the vendor's release process. Confirm the repository owner, the license, the maintainers listed on the package, and the last release date. Compare the plugin's supported Backstage version with your running version before you install it. Ask the vendor or community maintainers the questions you cannot answer from the repository, and record the answers in your plugin review note.
Limits to confirm in your environment before approving a plugin
This page does not assess any named plugin, and the facts that decide whether a plugin fits your portal change over time. The four cards below cover what you must confirm yourself at the time of review, from ownership and release line compatibility to Node.js support and the scopes an external API grants.
Current maintainer and repository
Confirm who maintains the plugin on the day you review it and where its code lives, since vendor-maintained plugins may change ownership or move to a different repository. Check the repository's recent commits, open issues and the named maintainers, and compare them with the location in your architecture notes. A plugin that moved after your last review is a new decision, so record the repository URL and review date in your approval file. Ask your procurement or security owner who accepts responsibility if the maintainer stops.
Compatibility with your Backstage release line
Confirm that the plugin declares support for the Backstage release line you run, because the main line ships monthly and the next line ships weekly. Read the plugin's release notes and compare them with the Backstage release notes on the GitHub releases page before you bump any @backstage package. A plugin that lags behind your release line blocks upgrades, so record the version pair you tested.
Node.js requirements against supported versions
Check the plugin's published Node.js engine requirements against the Node.js releases Backstage supports at your version. Backstage supports exactly two adjacent even-numbered Node.js releases, so a plugin that requires a single older or newer version can break your build or force a runtime change. Confirm the range in your container image and in your CI pipeline, not only on your workstation.
Scopes offered by the external API
Confirm that the external system's API offers the scopes the plugin needs, and no more. Read the plugin's documentation for each permission it requests, then check whether your chosen token type can grant a read-only scope for that data. If the API only issues broad tokens, record that risk and ask whether a narrower service account is possible. Credentials belong in backend configuration, never in frontend code.
How DeployOpen works on this
DeployOpen reviews candidate Backstage plugins against your organization's identity model, credential rules and delivery tools before anything reaches a production portal. The review produces a written decision for each plugin, along with the configuration and operating notes your team needs to keep it safe after handover.
How we scope
- Agree in writing which plugins are in the review and which Backstage version they must work with
- List the source systems each plugin would read from and the permissions each one would need
- Define the decision record format: maintainer, release activity, license and accepted risk per plugin
- Engagements are fixed-scope, so the scope, deliverables and timeline are confirmed before work starts
How we build
- Check each candidate's repository, maintainer and release history against the agreed criteria
- Install candidates in a non-production Backstage instance and test their sign-in and token handling
- Review the credentials and API scopes each plugin requests and propose narrower alternatives where possible
- Document any plugin that runs unsandboxed with the controls we recommend around it
How we hand over
- Deliver a decision record for each plugin with the evidence behind it
- Provide the approved plugin list, pinned versions and the configuration keys each plugin requires
- Document the steps to add, upgrade or remove a plugin under your change process
- Walk your platform and security teams through the findings and open questions
How we support
- Re-review plugins when their maintainers change, releases slow or a new Backstage line ships
- Ongoing support, upgrades and continuous testing are available as retainers
- Confirm any plugin's current status with its repository and your own environment before each change
- Keep the approved list and decision records current as your catalog and integrations grow
