How the Backstage Argo CD plugin shows sync and health
Teams open a Backstage service page and want to know one thing: is their Argo CD application synced and healthy right now, without logging into Argo CD. The Argo CD integration answers that question with a Backstage plugin that reads application state from one or more Argo CD instances through the Argo CD API. Backstage does not manage deployments itself. It displays what Argo CD already reports, so the portal is only as current as the API responses it receives. Each catalog entity is tied to its Argo CD application by an annotation that the chosen plugin documents, and the entity page shows the sync status and health status for the applications that carry that annotation.
The Argo CD side needs a dedicated account with read-only permissions, not an admin credential or a personal login. The token is held by the Backstage backend, never by the browser, and its scope should cover reading applications for the projects the portal is meant to show. Confirm with the plugin's documentation which Argo CD API permissions it calls, how it expects the token to be supplied, and whether it supports several Argo CD instances in one configuration. Check the Argo CD user management documentation for the account and RBAC settings that match your Argo CD version, since permission behavior changed in the 3.0 line.
The plugin choice, annotation key and token setup must be confirmed against the plugin's own documentation for the versions of Backstage and Argo CD you run. Plugin names, configuration keys and annotation syntax differ between the Roadie and Red Hat options and can change between releases, so treat any example in internal runbooks as illustrative until someone has verified it in a test instance. Before rolling out to all services, pick a few entities, confirm that the annotation resolves to the correct application, and check that a deliberately out-of-sync test application appears with the expected status.
What the Backstage Argo CD plugin needs before install
Six prerequisites decide whether the Argo CD plugin installs cleanly and stays supported. Each one is a separate check, and most failed installs trace back to a version mismatch, a missing network path or a credential scoped too broadly.
Supported Node.js runtime
The Backstage backend must run on a Node.js release that the Backstage versioning policy currently supports. As of Backstage 1.46.0 that means Node.js 22 or 24. Confirm the runtime in the image or host that runs the backend before you add any plugin packages, because a plugin cannot fix an unsupported runtime. Record the version in your deployment baseline so later upgrades start from a known state.
Matching Backstage release line
Choose the Backstage release line your plugin version targets before you pull packages. The main line ships monthly and the next line ships weekly. Check the plugin's documented compatibility against the current latest release and the next line, since both were published in late 2026. Pin the Backstage line first, then the plugin, so the two move together during upgrades.
Argo CD on a maintained patch line
Argo CD only backports patch releases to its three most recent minor versions. Confirm which minor line your clusters run and whether it is still in that window before you wire the plugin to it. An instance on an unsupported line keeps working but receives no fixes, which matters when the plugin depends on its API responses. Ask your platform team for the exact server version of each instance, not the version of the CLI.
Network path to each Argo CD API
The Backstage backend, not the browser, calls each Argo CD API endpoint, so the backend host needs a route and a trusted TLS chain to every instance. Map each Argo CD URL, including instances in separate clusters or accounts, and test the path from the exact pod or host that runs Backstage. Plan egress rules and certificate bundles with the network team, since a firewall rule that works from a laptop often fails from the cluster.
Read-scoped account per instance
Create one Argo CD account or token for each instance the plugin reads, with read-only permissions limited to the applications and projects that Backstage shows. Do not reuse the admin account, and do not give the plugin rights to sync, delete or change application settings. Store each token in a secret store your organization already operates, and plan rotation before go-live so a leaked token can be revoked without an outage.
Entities defined for each service
The plugin links Argo CD applications to catalog components through an annotation, so each service needs a component entity in the catalog before the plugin shows anything. Decide which entity owns each Argo CD application and who maintains the descriptor. Entities without owners or with inconsistent names produce pages that look empty, which teams often mistake for a broken plugin.
Choosing between the Roadie and Red Hat plugin options
Before you install anything, decide which of the two Argo CD plugins for Backstage fits your portal: the Roadie Argo CD plugin or the Red Hat Argo CD plugin. This is the one choice in this topic that is hard to reverse cheaply, because the plugin determines how your entity annotations are read, how credentials reach the backend, and how the plugin is upgraded alongside Backstage. This page does not rank the two. Your team should record its own findings from each plugin's repository and documentation, then commit to the option that matches its constraints.
Compare the options on five criteria, and write down the answer for each from the source material rather than from memory. First, the Backstage release line each plugin supports, checked against the release line your portal runs or plans to run (see the Backstage release and versioning policy). Second, how each handles several Argo CD instances, since many organizations run one instance per environment or per cluster group. Third, what each reads and displays: sync status, health status, and the application list, and whether it shows history or resource trees. Fourth, how each documents its annotation and token setup, including the annotation key the entity must carry and the account and permissions the API token needs. Fifth, who maintains the plugin, whether the maintainer is a vendor or a community group, and how often it publishes releases.
Record the findings in a short comparison table that your platform team can review, with a column for the source you checked and the date you checked it. Confirm the points that matter most in your own environment: a test Backstage instance connected to a non-production Argo CD, the annotation on one sample entity, and a token with the narrowest read permissions that still shows status. If a plugin's documentation does not state a supported release line, Argo CD version or instance model clearly, treat that as an open question to resolve with the maintainer before you select it.
Setting up the Backstage Argo CD plugin in order
This sequence takes a Backstage instance from version checks to a catalog entity that shows Argo CD sync and health status. Each step produces a check you can run before moving on, so problems surface at the stage where they are cheapest to fix.
Confirm Backstage, Argo CD and plugin compatibility
The platform engineering lead records the Backstage release line and Node.js version in use, the Argo CD minor version running on each cluster, and the plugin version that targets both. Check the plugin's README or release notes against your Backstage version, since plugin releases can lag behind core releases. The step is done when you have a written compatibility table with one row per Argo CD instance and a confirmed plugin version. Confirm the supported Argo CD patch line with the Argo CD release notes before choosing the version you plan to run.
Create a read-only Argo CD account for each instance
An Argo CD administrator creates a dedicated local account or SSO-backed role for the portal on each Argo CD instance, and grants it only read access to applications in the projects that Backstage should display. Under Argo CD 3.0 and later, check that the account can read application status and logs only where you have granted the explicit permissions, because log access needs its own permission. Generate a token for that account and record which instance it belongs to. The step is done when a direct API call with the token returns application list data for an allowed project and an error for a project it should not see.
Store each token in the backend secret store
The platform engineer places each Argo CD token in the secret store that the Backstage backend reads, such as environment variables injected by your deployment platform or an external secrets manager, using one secret name per instance. Reference those names from the backend configuration only. Confirm that the frontend bundle and the app-config file served to the browser contain no token values, and that the token does not appear in container logs at startup. The step is done when a search of the built frontend assets and the rendered configuration returns no match for the token string.
Install the plugin packages with the Backstage CLI
A Backstage developer adds the chosen plugin frontend and backend packages to the workspace using the Backstage CLI, which selects compatible versions for the current release line. Register the backend module in the backend index file and add the frontend plugin to the entity page components. Run the install and type-check commands from the repository root. The step is done when dependency resolution completes without peer dependency errors and the type check passes on the modified packages. Keep the install in a branch so the change can be reviewed alongside your other plugin additions.
Configure one entry per Argo CD instance
The platform engineer adds one configuration entry per Argo CD instance in the app configuration, each with a unique name, the instance base URL, and a reference to that instance's secret. Use the configuration keys documented by the plugin you chose, and do not place URLs or tokens in the frontend section. If you run several clusters, give each instance a stable name, because catalog annotations will refer to it. The step is done when the backend starts and logs a successful setup for every configured instance. Then run a test query against one instance and confirm it returns the application state for a known application.
Annotate a sample catalog entity
A service owner adds the annotation documented by the plugin to a sample component's catalog descriptor, pointing to the Argo CD application name and, where the plugin requires it, the instance name. Use a non-production component for the first test so that a mismatch does not affect real teams. Commit the descriptor and let the catalog refresh, or trigger a refresh manually. The step is done when the sample entity's catalog page loads without errors and the Argo CD card is present.
Restart the backend and verify sync and health
The platform engineer restarts the Backstage backend so the new configuration and secrets load, then opens the sample entity page. Confirm that the card shows the sync status and health status that match the Argo CD web interface for the same application, and that a second instance returns its own applications when you test it. Check the backend logs for authorization errors, which usually indicate a missing permission on the Argo CD account. The step is done when the displayed values match Argo CD for both the sample and one additional application.
How Backstage entities map to Argo CD applications
This table compares what each side of the link looks like in Backstage and in Argo CD, and the rule that ties them together. Read each row as a setting you must agree on before the plugin is configured, because a mismatch in any one of them leaves the entity page empty or showing the wrong application. The main takeaway is that the annotation value, the application name and the instance name must all point to the same Argo CD object.
| Backstage side | Argo CD side | Linking rule |
|---|---|---|
| Catalog entity name | Application name in the Argo CD instance | Use one owning Component entity per Argo CD application, named in a stable, lowercase form that teams can find |
| Plugin annotation on the entity (confirm exact key in the chosen plugin docs) | Application metadata that the plugin query matches | Set the annotation to the exact application name and namespace the plugin expects, and check it against the plugin README before rollout |
| Not applicable (no Backstage field) | Application name and namespace in the target cluster | Record the namespace explicitly if the plugin matches on it, since the same name can exist in more than one namespace |
| Configured instance name in the plugin config | The Argo CD server each application runs on | Give every instance a unique name in app-config so one entity annotation resolves to exactly one server |
| Not applicable (no Backstage field) | Argo CD project that scopes the application | Record the project so reviewers can see which team boundary and permissions cover the application |
| Sync and health states on the entity page | Sync status and health status of the application | Confirm the plugin shows both states and how it reports unknown or missing applications before relying on them |
| Applications with no matching entity | Applications with no owner annotation | Decide in advance whether these are hidden, reported to a catalog owner or cleaned up, and assign someone to review the list |
Connecting one or several Argo CD instances
A single Backstage portal can read from several Argo CD instances, one per cluster group, region or environment, but each instance has to be configured as its own named source. Decide the instance list before you touch the configuration: give every instance a stable, lowercase name that reflects its role (for example, a production group and a non-production group), and use that same name everywhere it appears, including the config block, the credential it uses and any documentation your teams read. Renaming an instance later means changing entity annotations across the catalog, so the naming decision is cheap to make now and expensive to reverse.
Give each instance its own API credential, scoped to read application status only. When every instance shares one token, a single revocation or rotation failure takes down the whole Argo CD view in Backstage, and the error is hard to trace back to one cluster group. Separate credentials also let you audit which instance a request came from. Keep the credentials in your secrets store and inject them into the backend, never into frontend configuration. Keep the annotation unambiguous as well: if the same application name exists in two instances, an entity that names only the application will match both, so the entity annotation should carry the instance identifier alongside the application name. Confirm the exact annotation keys and the multi-instance syntax against the documentation for the plugin version you install, because the supported format differs between the Roadie and Red Hat options.
Before you go live, check that the Backstage backend can reach every Argo CD API endpoint from the network zone where it runs. Portals are often deployed in a different zone from the clusters they report on, so a firewall rule that works for one instance may silently block another. Test each endpoint from the backend pod or host, not from your laptop, and confirm that TLS certificates validate against the trust store the backend actually uses. Argo CD's own high availability guidance and its multi-cluster setup belong in the Argo CD configuration plan, where you decide replicas, cluster registration and recovery. Backstage only reads from those instances, so a change to Argo CD topology should trigger a review of the Backstage instance list, not a change to Argo CD from the portal side.
Keeping Argo CD tokens out of the browser
The Argo CD plugin reads live delivery state, so its credentials carry real access to your clusters. The controls below cover where the token lives, how little it can do, how Argo CD and Backstage identities line up, and what to review before any plugin code runs.
Store tokens in backend configuration
Keep the Argo CD API token in backend secret configuration, read by the Backstage backend at runtime, and never in frontend config or the app-config file committed to Git. Any value the frontend bundle contains can be read by anyone who can load the portal in a browser. Ask your team to confirm that the token is injected from your secrets store into the backend environment during deployment, and that build output contains no copy of it.
Scope the Argo CD account narrowly
Create a dedicated Argo CD account for the portal and grant it only the get and list permissions it needs on the applications it displays, using project boundaries to limit which applications are visible. Avoid reusing the admin account or an engineer's personal token. Review the account's permissions each time you add a new Argo CD instance, since each instance needs its own credential.
Require explicit logs access
Since Argo CD 2.14 to 3.0, logs access needs an explicit logs, get permission in the RBAC policy, so update and delete rights no longer cover pod logs. Grant the logs permission only if the plugin or your users need log views, and document which roles hold it. Confirm this in your policy file, because older examples often grant broader access than the current model requires.
Disable the built-in admin user
Use the built-in admin user only for initial setup, then set admin.enabled to false once local users or SSO are configured. A remaining admin login is a standing path around your identity provider and audit trail. Ask whether anyone holds the admin password and whether it is stored in your secrets manager, then confirm the setting in the deployed configuration rather than in the intended one.
Align Backstage sign-in resolvers
Configure sign-in resolvers so every Backstage provider resolves a person to the same catalog identity, and turn guest access off in production. If GitHub and Okta sign-in create two identities for one engineer, the ownership and access decisions drawn from them will disagree. Test with a user from each provider and confirm that guest sign-in is refused in the deployed environment.
Check Argo CD 3.0 role mappings
Argo CD 3.0 moved repository definitions out of the argocd-cm ConfigMap into Kubernetes Secrets, and Dex-based RBAC now uses the federated_claims.user_id claim. Role mappings copied from pre-3.0 guides may silently grant nothing or match the wrong users. Test each mapping with a known account after any upgrade, and remove stale repository entries from the ConfigMap.
Review plugins before they run
Backstage plugins run unsandboxed inside the backend or frontend, so a plugin has the same reach as the code you deploy. Before install, review who maintains the plugin, its release history, the permissions and tokens it requests, and the source code that handles the Argo CD token. Record the reviewed version and pin it, so an upgrade cannot change the code without a new review.
Common failures in the Argo CD plugin and how to fix them
This table pairs each symptom a team is likely to see on an entity page or in the plugin backend with its probable cause and a check to run first. Read it from the symptom column, confirm the cause with the named check, then apply the fix. Most failures come from annotations, token scope or instance mapping rather than from Argo CD itself.
| Symptom | Likely cause | Fix and check to run |
|---|---|---|
| No Argo CD card on the entity page | The annotation is missing, misspelled, or the value does not match the Argo CD application name | Check the catalog-info.yaml annotation key and value exactly. Compare the value with the application name returned by the Argo CD API or the UI, then re-ingest the entity. |
| Authentication errors from the Argo CD API | The API token has expired, was created with a scope that cannot read applications, or was issued by a different Argo CD instance | Call the Argo CD API with the same token from the backend host. Confirm the token belongs to the instance named in the plugin configuration and has read access to the applications. |
| Empty or partial application data | The account behind the token cannot read the Argo CD project that holds the application, so some applications are filtered out | Check the account's project permissions in Argo CD RBAC. Compare the application list returned to the token with the list visible to a user who should see it, and grant read access to the project. |
| Backend fails to start after a Backstage version bump | The Argo CD plugin packages were not moved to the same Backstage release line as the rest of the @backstage packages | Run the version bump across all @backstage packages together with the Backstage CLI, then check the plugin's package version against the Backstage release line. Review the Backstage Upgrade Helper for template changes. |
| Timeouts to the Argo CD endpoint | The Backstage backend cannot reach the Argo CD API across a firewall, proxy or cluster network boundary, or the URL points at the wrong port | From the Backstage backend host, test the Argo CD API URL with a simple request and check DNS, egress rules and any proxy settings. Confirm the URL includes the correct scheme and port. |
| Status shown for the wrong instance | Two Argo CD instances contain an application with the same name, and the entity is not tied to a specific instance | Check the instance or cluster identifier in the entity annotations and the plugin's instance configuration. Confirm that each entity names the instance it belongs to and that the plugin queries that instance only. |
Questions teams ask before setting up the Argo CD plugin
Can our team set up the Argo CD plugin for Backstage without outside help?
Yes, a team can do this itself when it has one Argo CD instance and at least one engineer who already runs Backstage in production. The work is mostly configuration: installing the frontend and backend plugin packages, adding the Argo CD instance details to the Backstage configuration, and adding a argocd/app-selector annotation to each entity. Effort rises when you run several Argo CD instances, when your RBAC and SSO model is tied to Argo CD's Dex setup, when many entities need annotations, or when nobody on the team has upgraded Backstage before. Ask whether your team has someone who can own the token and the upgrade cycle after go-live.
What drives the effort of an Argo CD plugin integration?
Four factors matter most. The first is the number of Argo CD instances, since each one needs its own connection and credential. The second is the RBAC and SSO model: if Argo CD's project boundaries and Dex claims are mapped differently from your Backstage identities, the token scope and visibility rules need design work. The third is the number of catalog entities to link to Argo CD applications, which is largely a data cleanup task if ownership records are incomplete. The fourth is the plugin choice and version alignment with your Backstage release line, because each plugin must be bumped with the rest of the @backstage packages during routine upgrades. Confirm each factor with your own inventory before asking for a quote.
What does our organization need to provide for the integration?
Plan to provide four things. First, access to each Argo CD instance, including a dedicated read-only account or an API token created for Backstage, plus the permission to review its project and application scope. Second, catalog ownership data: each component needs an owner and a known Argo CD application name or selector. Third, network paths from the Backstage backend to every Argo CD API endpoint, which often requires firewall or proxy changes in regulated networks. Fourth, a named owner who holds and rotates the token and receives alerts when the integration breaks. Ask your delivery partner to list these items in the written scope so each one has an owner before work starts.
Do the Backstage and Argo CD plugins have license fees?
Neither project charges for its software. Backstage is released under the Apache License 2.0, and Argo CD is also released under the Apache License 2.0, with no paid edition from either project. The Argo CD plugin options come from the Roadie and Red Hat ecosystems, and their licenses are not covered by the project licenses above, so check the license file in each plugin repository before installing it. Your costs will generally be infrastructure to run Backstage and Argo CD, staff or partner time for setup, and ongoing maintenance. Ask any vendor for written confirmation of the plugin license and of any commercial terms that apply to the plugin's host platform.
How long does setting up the Argo CD plugin take?
The duration depends on the scope: the number of Argo CD instances, how many entities need linking, how much identity and network work is needed, and whether ownership data is already clean. A single instance with a small, well-annotated catalog is a much shorter task than a multi-instance rollout with strict project boundaries. DeployOpen provides a timeline only in the written, fixed-scope agreement, after the scope, deliverables and dependencies are agreed. Before asking for that agreement, confirm your instance count, your entity count and whether your network and token approvals are already in place, since those are the most common sources of delay.
How do Backstage and Argo CD upgrades affect the plugin integration?
Each upgrade can change the plugin, the Backstage packages it depends on, or the Argo CD API it calls. Backstage upgrades move all @backstage packages together with yarn backstage-cli versions:bump, and the Backstage Upgrade Helper shows template changes between versions, so the plugin must be checked on every bump. Argo CD also changes behavior between major versions: its 2.14 to 3.0 notes changed RBAC for applications and logs access, so a token that could read logs before may need an explicit permission after an upgrade. Argo CD patch releases continue for its three most recent minor versions. Plan a test environment for the plugin, and add the integration to your upgrade checklist for both platforms.
Should the Argo CD token be shared across the whole Backstage instance?
A single, read-only service credential per Argo CD instance is the simplest model, and it is usually enough for status display. It means every Backstage user sees the same application data that the token can read, so check whether that matches your Argo CD project boundaries. If some applications must be hidden from certain teams, you need a model that separates visibility by identity, and that work is part of the scope. Store the credential in your secrets manager, keep it out of the frontend bundle, and confirm the plugin's token permissions with the plugin maintainer before you grant access.
How DeployOpen scopes and supports the Argo CD integration
DeployOpen plans the Backstage Argo CD plugin setup as a fixed-scope piece of work inside your own Backstage and Argo CD environment. We agree on which instances, entities, credentials and sign-in controls are in scope before any configuration begins, then document and hand over the result so your team can run it.
How we scope
- Inventory every Argo CD instance, cluster and project that the portal must read from.
- Agree which catalog entities will be linked to Argo CD applications and which annotation convention they will use.
- Confirm the plugin option, the Backstage version in use and the Argo CD version each instance runs.
- Record the credential model, token scopes and role boundaries in the written scope before work starts.
How we build
- Configure the chosen Backstage plugin in a non-production instance connected to a test Argo CD environment first.
- Map each sample catalog entity to its Argo CD application and confirm sync and health status display correctly.
- Store Argo CD credentials in your secrets system and keep them out of frontend configuration and the browser.
- Test access so users see only the applications their Argo CD roles and Backstage identities allow.
How we hand over
- Document the configuration, annotation standard, token rotation steps and the steps for adding a new Argo CD instance.
- Provide a verification checklist that your team can rerun after upgrades of Backstage, the plugin or Argo CD.
- Walk your engineers through troubleshooting for missing statuses, mismatched entity links and expired tokens.
- Deliver the work in your own repositories so your team owns the configuration and history.
How we support
- Offer ongoing support, plugin upgrades and continuous testing as a retainer after the initial handover.
- Review plugin and Argo CD version changes against your configuration before you upgrade either side.
- Confirm with the plugin maintainer and Argo CD release notes which changes affect your setup, and tell you what to check.
- Quote any follow-on work from a written scope so cost and timing stay visible to your team.
