How the Backstage Jenkins plugin shows build status on entity pages
Teams want to know whether their latest Jenkins build passed or failed without leaving the portal. The Backstage Jenkins plugin answers that need by reading job status and build history from the Jenkins API and displaying them on an entity page, but only for catalog entities that carry the jenkins.io/job-full-name annotation. The annotation value must match the job's full name in Jenkins, including any folder path, so the link between a component and its pipeline is an explicit, reviewable line in the descriptor rather than an inferred name match. Because the plugin is a community project, the exact package name, its maintainer, its release activity and its compatibility with the Backstage version you run must be confirmed in the plugin's own repository before anything is installed.
The plugin is not one component. It has a frontend view that renders on the entity page and a backend part that makes the calls to Jenkins, so you need to decide where the Jenkins credential lives and how the backend is wired into your deployment. Where more than one Jenkins instance exists, for example one controller per business unit, the configuration must name each instance and each entity must point to the right one. Confirm that the plugin supports that multi-instance layout in its documentation, and confirm how it handles an entity whose annotation names a job that does not exist on the instance it queries. Plan these checks as part of the design, since they determine how many instances the catalog can represent cleanly.
DeployOpen plans the Jenkins work only after that check is complete. We confirm the package, its maintainer and its compatibility with your Backstage release, then document the annotation convention, the instance map and the token scope the plugin needs. The API token should be a dedicated, read-only identity limited to the jobs the portal must display, and it should be stored in your secrets system rather than in the frontend configuration. Ask your Jenkins administrators to confirm which controllers and folders are in scope, because the token's permissions set the boundary of what the portal can show.
What you need before connecting Backstage to Jenkins
Connecting the Backstage Jenkins plugin touches four systems: the portal, its Node.js runtime, the Jenkins controllers and the identity the portal uses to read job data. Settle the versions and access paths on each side before you write any annotations, because most connection failures trace back to one of these foundations.
Backstage release line and Node.js
Start by pinning the Backstage release line your portal runs, since the Jenkins plugin must match it. Backstage supports exactly two adjacent even-numbered Node.js releases, and as of Backstage 1.46.0 those are Node.js 22 and 24, so confirm the current pair for your release before choosing a runtime. Check the plugin's own version compatibility with that Backstage release before pinning anything, and record both versions in your change log.
Jenkins LTS line in use
Decide which Jenkins LTS line your controllers run and track its patch cadence, since the plugin is tested against the release you choose rather than against every weekly build. Jenkins LTS 2.580.1 was released on September 30, 2026, following 2.568.3 on September 2, 2026. Confirm the plugin version works with that baseline and plan a window to test upgrades on a staging controller first.
Java runtime on each controller
Confirm the Java version each Jenkins controller runs on before you install plugins that require a newer baseline. Java 21 and Java 25 are listed as supported by Jenkins, with Java 17 ending at the final LTS release 2.541.3 in March 2026. Controllers still on Java 17 need a runtime change before you upgrade, and you should check that the plugin manager reports no incompatibilities after the change.
Network paths from the backend
The plugin calls each Jenkins controller from the Backstage backend, not from the browser, so the backend pod or host needs a route to every controller's HTTP or HTTPS endpoint. List each controller hostname and port, and confirm that proxies, firewall rules and TLS certificate chains allow the backend to reach them. Ask the Jenkins team whether controllers sit behind a load balancer, since the health of a failover pair affects which URL you configure.
Dedicated Jenkins service account
Create a Jenkins user or service account reserved for the portal rather than reusing a personal login. The account needs read access to the jobs it will display, and nothing more, so scope its permissions to the folders or jobs that map to catalog entities. Generate an API token for that account and store it in your secrets manager, because a shared personal token would break when someone leaves the team and would give the portal more reach than it needs.
Plugin version and token scope check
Before you pin versions, confirm the Jenkins plugin release supports both your Backstage release and your Jenkins baseline. Record the token scope the plugin needs, then test it against one controller with a read-only account. Treat the check as a gate: if the plugin version, Backstage release or token permissions do not match your test results, resolve them before you add annotations to production entities.
Configuring the Backstage Jenkins plugin with job-full-name annotations
This sequence connects one Jenkins instance to a Backstage test deployment, maps a single component to its Jenkins job, and confirms that the entity page shows the same status as Jenkins. It gives your team a verified pattern to repeat before rolling the plugin out to other teams.
Confirm plugin source and version compatibility
Before installing anything, confirm which Jenkins plugin package you intend to use and where it is maintained. Check the plugin's listing and its repository for the Backstage version it targets, and compare that against the Backstage release line your portal runs, which you can confirm in your repository's package manifests. Also confirm that your Jenkins controller runs a supported LTS line, since the plugin depends on the controller's API. Record the plugin name, version and Backstage target in your change ticket. The check is done when someone on the team can state which plugin version matches your Backstage version and which Jenkins controller version it was tested against.
Install frontend and backend packages with the CLI
A platform engineer adds the Jenkins frontend and backend packages to the Backstage app using the Backstage CLI, so the packages resolve to the same @backstage versions already in the repository. Run the install from the repository root, then register the frontend component on the entity page and the backend plugin in the backend entry point, following the plugin's own installation notes. Commit the changes on a branch rather than editing the lockfile by hand. The check is done when the app builds locally and the backend starts without module resolution errors.
Register the Jenkins connection with a secret token
In the backend configuration file for your Backstage app, add the Jenkins instance base URL and the username and API token the plugin uses to query job status. Reference the token through an environment variable or secret store rather than writing it into the committed configuration file, so it never appears in source control or the frontend bundle. Ask Jenkins for a dedicated service account and create the API token for that account. Confirm the token scope is read-only for the jobs you intend to show, which is the narrowest permission that allows status and history queries. The check is done when the backend starts and the connection block resolves the token from the environment at runtime.
Annotate one test component descriptor
Choose one non-production component in your software catalog and add the jenkins.io/job-full-name annotation to its catalog-info.yaml descriptor. The value must be the full path of the Jenkins job, including every parent folder, separated by slashes. For example, a job named build inside a folder named payments on the controller would be written as payments/build (illustrative). Check the path by opening the job in the Jenkins web interface and reading the breadcrumb trail, since a mismatch is the most common cause of an empty entity page. The check is done when the descriptor is merged to the catalog source and the catalog reloads the entity with the annotation visible.
Restart the backend and watch for auth errors
Restart the Backstage backend so it reads the new configuration and the catalog entity with its annotation. Watch the backend logs during the first few requests to the Jenkins plugin. Authentication failures usually appear as rejected requests or unauthorized responses from the Jenkins controller, and they typically point to a wrong username, an expired or copied-incorrectly token, or a token issued to a different account. Fix the token source and restart if errors appear. The check is done when the logs show successful requests to the Jenkins controller and no authentication errors for the test component.
Compare the entity page with the Jenkins job
Open the test component's entity page in Backstage and locate the build section added by the plugin. Then open the same job in Jenkins and compare three things: the job name and path should match the annotation, the status shown should match the result of the most recent build, and the build history list should show the same run numbers in the same order. Trigger a build in Jenkins if the last run is stale, then refresh the entity page to confirm the status updates. Record any differences and check the annotation first. The check is done when the entity page and the Jenkins job agree on job path, latest status and recent history for the test component.
Plan multiple Jenkins instances before scaling
If your organization runs more than one Jenkins controller, decide before adding more annotations how the plugin will identify which controller owns a job. Confirm with the plugin's documentation whether it supports multiple instance definitions in configuration and how the annotation selects among them. Also note that Jenkins recommends adding controllers for new teams or projects rather than one shared controller, so your mapping should follow that ownership model. Document each instance, its token account and its catalog owners in your runbook. The check is done when your team has a written list of controllers, token accounts and the annotation format each instance requires, and the test component works against each controller you plan to connect.
Single Jenkins controller or several: choosing the connection layout
A single Jenkins controller that holds every team's jobs is the simplest layout to connect. The jenkins.io/job-full-name annotation on each entity is enough to identify the job, because the job name is unique on that controller, and one API token with one scope governs what Backstage can read. Setup means one base URL, one credential stored as a secret, and one plugin configuration block.
- Job naming: Confirm that every entity's annotation matches the full job path exactly, including folder segments used by multibranch pipelines.
- Token scope: Create a dedicated user for Backstage with read-only permissions on the jobs it displays, and avoid reusing a personal administrator token.
- Blast radius: A single token that leaks exposes every job on the controller, so rotation and storage matter more here than in the other layouts.
- Controller load: Read requests from the portal add to controller traffic, so check the scaling guide's advice to keep the controller focused on HTTP requests and move builds to agents.
- Growth: This layout stops fitting once teams need separate plugins, separate upgrade windows or separate access boundaries.
Before you commit to this layout, confirm with your Jenkins administrators that no team needs isolation from the others on the same controller.
The Jenkins scaling guide describes adding controllers for new teams or projects as a common way to grow, and that pattern is common in organizations with independent teams. Each controller then has its own jobs, plugins, credentials and $JENKINS_HOME. Backstage needs to know which instance an entity belongs to, so each entity must name its instance as well as its job, and each instance needs its own connection and token.
- Instance identification: Decide how each entity records its controller, such as an annotation or a naming convention, and apply it consistently across the catalog.
- One token per instance: Create a separate read-only credential on each controller so one compromised token does not expose the others.
- Connection configuration: Define one connection per controller in the plugin configuration and store each credential as a secret.
- Support check: Confirm in the plugin's current documentation that it supports multiple Jenkins instances and how it selects between them.
- Operations: Each controller adds upgrade, backup and token rotation work, so count those tasks when comparing this layout with a shared controller.
Before you build this layout, ask your Jenkins owners for the list of controllers and confirm which team owns each one.
A primary and backup arrangement places a proxy such as HAProxy or F5 in front of two controllers so traffic moves to the backup if the primary fails, as the Jenkins scaling guide describes. The layout raises a design question for Backstage: whether the connection points at the proxy address or at each controller directly. The answer depends on how the proxy handles failover and how the plugin reacts to a change of backend.
- Proxy address: Pointing Backstage at the proxy keeps one configuration block and lets failover stay invisible to the portal, but it depends on the proxy passing the API requests and authentication headers correctly.
- Direct addresses: Pointing at each controller lets you see which one answered, but requires logic or manual steps when the primary fails.
- Credentials: Both controllers must accept the same Backstage token or each needs its own, so confirm how the backup is kept in sync.
- Health checks: Ask the proxy team how failover is detected, since a slow primary may not trigger it.
- Ownership: Agree who owns the proxy configuration, because a change there affects the portal.
Before you choose, test a failover in a non-production environment and confirm that the plugin still shows job status afterward.
Mapping catalog entities to Jenkins jobs and status fields
This table maps each Backstage catalog field to the Jenkins value it relies on, so you can check which entity fields drive job lookup and which only appear as context. Read it alongside the plugin's current documentation, since field names and selectors can change between releases. The main takeaway is that the entity page reflects what Jenkins reports for the job, so a Jenkinsfile change shows up only after Jenkins runs it.
| Backstage field | Jenkins value or behavior | What to confirm |
|---|---|---|
| Entity name (metadata.name) | Catalog identifier only. It does not select a Jenkins job on its own. | Confirm the plugin does not derive the job path from the entity name. |
| jenkins.io/job-full-name annotation | Full job path in Jenkins, including any folder segments. | Confirm the folder separator and the exact path format the plugin expects. |
| Instance selector (when several controllers exist) | Identifies which Jenkins controller URL the plugin queries for this entity. | Confirm the annotation or configuration key that selects the instance and its default. |
| spec.owner | Catalog metadata shown with the build status. The plugin does not notify owners. | Confirm whether owner appears on the card. Failure alerts need a separate route. |
| Displayed build status | Result of the latest build reported by the Jenkins API, such as success, failure or unstable. | Confirm which result and in-progress states the plugin displays and how it maps them. |
| Last build number | Build number of the job's most recent build reported by Jenkins. | Confirm whether the number comes from the last build or the last completed build. |
| Build history | Recent builds of the job as Jenkins returns them through the API. | Confirm how many builds the plugin lists and whether pagination is configurable. |
| Stage names | Defined by the Jenkinsfile in source control and executed by Jenkins. Stage detail appears only if Jenkins reports it. | Confirm whether the plugin shows stage-level results or only job-level results. |
API token scope for the Backstage Jenkins plugin
The Jenkins token is the one credential the portal holds that can reach your build system, so its scope matters as much as the plugin setup. The cards below cover the account the token belongs to, where it is stored, how traffic reaches the controllers, how sign-in shapes who can view the data, how the token is rotated, and where configuration-as-code fits in.
Use a dedicated read-only account
Create a separate Jenkins user for the Backstage backend and give it only the read permissions needed to display the jobs the portal shows. Do not use an administrator account or a personal account, because the token would inherit that person's rights and would stop working when they leave. Confirm the exact permissions the plugin needs in its own documentation before you grant anything, and test that the account cannot trigger builds or change configuration. Ask your Jenkins administrators to review the role assignments once a year.
Store the token in the backend only
Keep the Jenkins API token in backend configuration that reads it from a secret store or environment variable, never in a value written into the app-config file that lives in the catalog repository. Confirm that the token does not appear in the frontend bundle or in any value exposed to the browser, since anyone with page access could read it. Check your container image and CI logs for accidental echoes of the variable during builds.
Restrict network paths to controllers
Allow only the Backstage backend to reach your Jenkins controllers, and only on the HTTP port they serve, using firewall rules, security groups or network policies. Engineers and the browser should not need a direct route to the controllers for this plugin to work. If you run several controllers, list each one as an allowed destination so that a single compromised pod cannot reach unrelated systems. Verify the path from a pod outside the backend to confirm it is blocked.
Remove guest access and map identities
Turn off guest sign-in in production and configure sign-in resolvers so every identity provider resolves to the same catalog user. The authentication guidance advises this so that a person sees Jenkins data only through an identity your organization controls. Without it, an anonymous visitor or a second login path could reach pages that show build information. Confirm the resolver rules with a test user from each provider you enable.
Rotate the token on a schedule
Write a rotation procedure that creates a new token for the dedicated account, updates the secret store, restarts the backend, confirms that job status still loads, and then revokes the old token. Agree on an interval with your security team and record each rotation as change evidence. Also define what happens after a suspected leak: revoke first, then rotate, then review Jenkins audit records for the account. Practice the steps in a non-production environment before you rely on them.
Keep configuration as code separate from plugins
If you manage Jenkins with the Configuration as Code plugin, remember that it reads settings from YAML, located through the CASC_JENKINS_CONFIG variable with a default under $JENKINS_HOME, but it does not install plugins. Install the Jenkins plugins your Backstage integration needs through your image or Helm chart, and keep the token reference in the YAML as a secret, not a literal value. Review the YAML in the same change process as your Jenkins configuration so that permission changes are visible.
Why build status is missing or wrong on entity pages
This table maps the symptoms teams most often see on a Jenkins card in Backstage to their likely causes and the checks that confirm each fix. Read it from the symptom column: find what the entity page shows, then work down the cause and fix columns in order. Most failures trace to the annotation, the job path, or the token, so check those before changing the Jenkins controller.
| Symptom | Likely cause | Fix |
|---|---|---|
| The Jenkins card shows nothing on the entity page | The jenkins.io/job-full-name annotation is missing or misspelled in catalog-info.yaml, or the entity has not been re-ingested since the annotation was added | Correct the annotation key in the descriptor, commit it, then trigger a refresh of the entity in the catalog and reload the page to confirm the card appears |
| The card shows the wrong job or no build history | The job-full-name value uses the job's short name and omits the folder path, so Backstage looks up a job that does not exist at that path | Copy the full path from the Jenkins job URL, including each parent folder segment, and set the annotation to that exact value; open the job in Jenkins to verify it matches |
| Backend logs show 401 or 403 responses from Jenkins | The API token was rotated or revoked, has expired, or was generated for an account that lacks read access to the job | Generate a new token for a service account with read access to the target jobs, store it in the backend secret store, restart the backend, and confirm a 200 response on the job's API endpoint |
| Backend logs show TLS or certificate errors | Backstage does not trust the certificate chain of the Jenkins controller, or a proxy or load balancer is routing requests to a backup controller that uses a different certificate | Add the internal CA to the backend's trust store, and confirm the proxy health checks point at the active controller; test the URL with curl from the Backstage backend host using the same trust store |
| Status is stale or the card errors after a Jenkins upgrade | The plugin is not compatible with the new Jenkins LTS line, or a plugin the controller relied on, such as the JUnit plugin, was removed from the bundle in 2.580.1 and is no longer present | Check the Jenkins LTS changelog for removed bundled plugins, install any required ones through the plugin manager, and update the Jenkins plugin in Backstage to a version tested against your controller's LTS line |
Questions teams ask before connecting Jenkins to Backstage
What drives the cost and effort of connecting Jenkins to Backstage?
The main drivers are the number of Jenkins controllers, the number of jobs that need the jenkins.io/job-full-name annotation on catalog entities, how the API token and sign-in identity are set up, and how much testing you need across Backstage and Jenkins upgrades. Each controller adds its own plugin configuration and token decision, so one controller serving a few teams is much smaller work than several controllers with different folder layouts. Annotation rollout is often the slowest part because owning teams must update their catalog files. Setup is one-time work, while upgrade testing recurs. Ask any quote to itemize controllers, job count, annotation coverage, token setup and upgrade testing separately.
Can our own team connect Jenkins to Backstage without a partner?
Yes, if you already run Backstage and Jenkins, have administrators who can change both, and have a non-production environment to test in. The work touches the Backstage app configuration, catalog annotations, the Jenkins token account and the plugin version, so the team needs someone comfortable with each part. In practice, that means a Backstage administrator with access to the app configuration and catalog repositories, a Jenkins administrator who can create a read-only token account, and a test controller that mirrors your production job layout. Without a test environment, the first Backstage or Jenkins upgrade becomes your test. A partner is most useful where one of these skills is missing. Confirm the skill mix against your own environment before deciding.
How long does a Jenkins to Backstage integration take?
The duration depends on the scope and your environment, so no fixed timeline applies to every organization. The main variables are the number of controllers, how many entities need annotations, whether the token account needs an approval cycle, and how soon you can schedule changes in production. Most engagements are fixed-scope, and scope, deliverables and timelines are agreed in writing before work starts. Ask for the written scope to list each controller and its jobs, the dependencies on your test environment and approvals, and the change windows the timeline assumes. Also ask what happens to the timeline if an approval or access request stalls.
What do we need to provide for a Jenkins plugin engagement?
You need to provide named owners, access and a few decisions before work starts. The required items are:
- A named owner on the Backstage side who can approve configuration and catalog changes.
- A named owner on the Jenkins side who can install plugins and create tokens.
- Jenkins access with rights to install the plugin and read job data on each controller in scope.
- A test controller, or a staging copy of production, where the integration can be verified before go-live.
- A decision on the token account, which should be a dedicated service account with read-only permissions rather than a personal user account.
Agree these items in the written scope so that delays are visible early.
Is the Jenkins plugin for Backstage safe to install?
Treat any third-party Backstage plugin as code that needs review before installation, because plugins run unsandboxed and with the access the portal gives them. Work through a vetting checklist first: who maintains the plugin, whether it sits in the community plugins repository or a vendor repository, how recently it was released, and which permissions and credentials it requires. The Jenkins project itself is distributed under the MIT License, which is a separate question from the plugin's maintenance and access needs. Confirm the plugin's source, release history and token requirements in your own review, and use a token with read-only scope. The vetting checklist in this plugins group covers the full review.
What happens after go-live with the Jenkins plugin?
After go-live, the plugin needs upgrades that track two release cadences: Backstage and Jenkins LTS. The Backstage main release line ships monthly, and its policy backports high and critical vulnerabilities to releases from the last six months where feasible. Jenkins publishes LTS releases in four-week cycles that contain backported fixes only. Jenkins LTS 2.580.1, released September 30, 2026, stopped bundling several plugins, so administrators who rely on them must install them through the plugin manager. Each upgrade should be tested on the staging controller before production. Ongoing support, upgrades and continuous testing are available as retainers.
How DeployOpen scopes and delivers the Backstage Jenkins integration
DeployOpen starts with a written scope that maps your Jenkins controllers, jobs and entity ownership to the Backstage catalog before any configuration changes. We then build and test the integration in your own infrastructure, document it, and hand it over to your team, with ongoing support available as a retainer.
How we scope
- Inventory every Jenkins controller and confirm which ones teams use for builds and deployments.
- Map each catalog component to its Jenkins job full name so annotation values are agreed before work starts.
- Agree in writing which token scope, plugin versions and entity pages are in the fixed-scope deliverable.
How we build
- Install and configure the community Jenkins plugin in your Backstage instance, with the Jenkins connection kept on the backend.
- Add the jenkins.io/job-full-name annotation to catalog descriptors and check that each entity shows the expected job history.
- Test failed, running and folder-nested jobs, plus connections to each Jenkins instance, against your own sample components.
How we hand over
- Document the annotation convention, controller connections, token ownership and rotation steps for your platform team.
- Walk your engineers through the configuration files and the checks used to confirm each entity shows correct build status.
- Record the plugin and Backstage versions tested so later upgrades can be compared against a known working state.
How we support
- Ongoing support, plugin upgrades and continuous testing are available as a retainer after the handover.
- Review plugin and Jenkins version changes, such as Jenkins LTS updates, before they reach your production portal.
- Ask any provider, including DeployOpen, to confirm the plugin's current maintenance status and compatibility with your versions.
