Backstage Jenkins Plugin

Jenkins is an open source automation server to build, test, and deploy software. It lets you execute a series of actions to build a continuous integration pipeline. Jenkins is well known for its extensive set of plugins.

The Jenkins Backstage plugin brings builds data associated with your services to your Developer Portal. The plugin can pull build information from a GitHub Organization project in Jenkins. Other Jenkins project types like Freestyle project and Pipeline are not supported yet.

In this guide you’ll find:

Installation steps
Required annotations
How to get a Jenkins API token
Setting up Jenkins locally
Supported types of Jenkins projects

Installation Instructions

These instructions apply to self-hosted Backstage only. To use this plugin on Roadie, visit the docs.

Install the plugin.

Copy

cd packages/app
yarn add @backstage/plugin-jenkins

Add the plugin API to your Backstage app.

Copy

// packages/app/src/components/catalog/EntityPage.tsx
import { EntityJenkinsContent } from '@backstage/plugin-jenkins';

// add new Jenkins tab to the service component page
const serviceEntityPage = (
  <EntityLayout>
    ...
    <EntityLayout.Route path="/jenkins" title="Jenkins">
      <EntityJenkinsContent />
    </EntityLayout.Route>
    ...
  </EntityLayout>
);

Add proxy configuration to your Backstage app’s config. A Jenkins API token is required. See how to get a Jenkins API token below.

Copy

// app-config.yaml
proxy:
  '/jenkins/api':
    target: 'http://localhost:8080'
    changeOrigin: true
    headers:
      Authorization: Basic ${JENKINS_BASIC_AUTH_HEADER}

Add Jenkins plugin annotation to your component’s config. ()

Copy

// catalog-info.yaml
metadata:
  annotations:
    # instanceName and github-organization-project-name are optional. The value is a string and should be enclosed in double quotes ""
    jenkins.io/job-full-name: "instanceName:github-organization-project-name/job-name"

Things to Know

Your Backstage app’s backend connects to your Jenkins server using the Jenkins API. A Jenkins API token is required. This token can be obtained from a system environment variable (ex. JENKINS_BASIC_AUTH_HEADER) containing a base64 encoded string.

Access the settings page of the Jenkins user for which you want to create an API token. For example, for a user named “admin” on a local Jenkins server: http://localhost:8080/user/admin/.
Add a new token under the ‘API Token’ section. Copy the token before leaving the page.
Construct a base64 encoded basic authorization string using your Jenkins user’s name and the API token. For example, in a Bash shell:

Copy
```
echo -n admin:1147f3bd451f3c48b8f21fd3aba13e58eb | base64
```
Save the base64 encoded string to an environment variable named JENKINS_BASIC_AUTH_HEADER. This variable can be used in the Jenkins proxy configuration in your Backstage app’s app-config.yaml.

Setting up a local Jenkins environment

If you want to try out this plugin but you don’t have a Jenkins server to test it with, you can quickly setup a local Jenkins server with docker. See the instructions available in the official Jenkins Docker GitHub repo.

Supported types of Jenkins projects

The plugin can pull build information from a GitHub Organization project in Jenkins. Other Jenkins project types like Freestyle project and Pipeline are not supported yet.

Jenkins menu to create new items

The plugin shows a list of the most recent builds in Backstage. This list includes builds from all projects that are available in the GitHub Organization project in Jenkins.

Jenkins and Backstage side-by-side

View additional build information by selecting a build from the list.

Backstage Jenkins job details

Changelog

This changelog is produced from commits made to the Jenkins plugin since a year ago, and based on the code located here. It may not contain information about all commits. Releases and version bumps are intentionally omitted. This changelog is generated by AI.

Breaking changes

Drop legacy backend support in the Jenkins backend. Migrate to the new backend system. #2589 merged 8 months ago
Earlier deprecate the legacy backend. #2050 merged 10 months ago

Features

Add multi project support in the Jenkins plugin. The job full name annotation now accepts multiple comma separated values. All jobs must be from the same Jenkins instance. #2518 merged 8 months ago
Add an API to fetch build console text. This lets other components read the Jenkins build console output. #2172 merged 9 months ago
Add title prop to EntityJenkinsContent and EntityLatestJenkinsRunCard. #1940 merged 10 months ago
Add more Jenkins scaffolder actions. New actions include build copy create create with file destroy disable enable. #2903 merged 3 months ago
Introduce the Jenkins scaffolder module with a create job action. #1481 merged 11 months ago

Improvements

Improve backend config. Remove the strict read of the top level jenkins key. Add clearer schema checks at build time for single instance or instances array. #2859 merged 6 months ago
In the new frontend system hide Jenkins components when the required annotation is missing. This avoids empty states. #2020 merged 10 months ago

Bug fixes

Sanitize user input used to build Jenkins API URLs. #3009 merged 6 months ago
Expose Jenkins permissions metadata from the backend builder. Fix the permissions metadata endpoint. #3119 merged 7 months ago

Documentation

Fix a typo in the Jenkins readme. #2086 merged 10 months ago

Maintenance

Remove the deprecated createRouter from the Jenkins backend. #3165 merged 5 months ago
Remove unused canvas dev dependency. Includes Jenkins packages. #3565 merged 5 months ago
Clean up knip config to cut false positives. Includes Jenkins packages. #3018 merged 6 months ago
Release the Jenkins scaffolder module. Move its directory and add the missing changeset. #1768 merged 11 months ago
Remove the private flag from the Jenkins scaffolder package so it can be used. #1721 merged 11 months ago

Set up Backstage in minutes with Roadie

Focus on using Backstage, rather than building and maintaining it.

Get a demo