roadiehq/backstage

Backstage is an open platform for building developer portals

Note

🏖 From July 1st through 16th, due to maintainers being on summer vacations, expect the project to move a little slower than normal, and support to be limited. Normal service will resume after that! 🏝

Backstage

English | 한국어 | 中文版 | Français

What is Backstage?

Backstage is an open source framework for building developer portals. Powered by a centralized software catalog, Backstage restores order to your microservices and infrastructure and enables your product teams to ship high-quality code quickly without compromising autonomy.

Backstage unifies all your infrastructure tooling, services, and documentation to create a streamlined development environment from end to end.

Out of the box, Backstage includes:

• Backstage Software Catalog for managing all your software such as microservices, libraries, data pipelines, websites, and ML models
• Backstage Software Templates for quickly spinning up new projects and standardizing your tooling with your organization’s best practices
• Backstage TechDocs for making it easy to create, maintain, find, and use technical documentation, using a "docs like code" approach
• Plus, a growing ecosystem of open source plugins that further expand Backstage’s customizability and functionality

Backstage was created by Spotify but is now hosted by the Cloud Native Computing Foundation (CNCF) as an Incubation level project. For more information, see the announcement.

Project roadmap

For information about the detailed project roadmap including delivered milestones, see the Roadmap.

Getting Started

To start using Backstage, see the Getting Started documentation.

Documentation

The documentation of Backstage includes:

• Main documentation
• Software Catalog
• Architecture (Decisions)
• Designing for Backstage
• Storybook - UI components

Community

To engage with our community, you can use the following resources:

• Discord chatroom - Get support or discuss the project
• Contributing to Backstage - Start here if you want to contribute
• RFCs - Help shape the technical direction
• FAQ - Frequently Asked Questions
• Code of Conduct - This is how we roll
• Adopters - Companies already using Backstage
• Blog - Announcements and updates
• Newsletter - Subscribe to our email newsletter
• Backstage Community Sessions - Join monthly meetups and explore Backstage community
• Give us a star ⭐️ - If you are using Backstage or think it is an interesting project, we would love a star ❤️

License

Copyright 2020-2024 © The Backstage Authors. All rights reserved. The Linux Foundation has registered trademarks and uses trademarks. For a list of trademarks of The Linux Foundation, please see our Trademark Usage page: https://www.linuxfoundation.org/trademark-usage

Licensed under the Apache License, Version 2.0: http://www.apache.org/licenses/LICENSE-2.0

Security

Please report sensitive security issues using Spotify's bug-bounty program rather than GitHub.

For further details, see our complete security release process.

backstage's Issues

Error when trying to start backstage...

I'm trying to start backstage and am getting the following error:

$ yarn workspace example-app start
$ yarn workspace example-backend start
$ backstage-cli app:serve
$ backstage-cli backend:dev
[0] 
[0] Error: No existing version was accepted for range ^0.9.3, searching through 0.9.2,0.8.4, for package @backstage/catalog-model
[0] 
error Command failed with exit code 1.
info Visit https://yarnpkg.com/en/docs/cli/run for documentation about this command.
error Command failed.
[0] Exit code: 1
[0] Command: /usr/local/bin/node
[0] Arguments: /Users/chwilliams/eig/backstage-curtain/bsdev/.yarn/releases/yarn-1.22.1.js start
[0] Directory: /Users/chwilliams/eig/backstage-curtain/bsdev/packages/app
[0] Output:
[0] 
info Visit https://yarnpkg.com/en/docs/cli/workspace for documentation about this command.
error Command failed with exit code 1.
info Visit https://yarnpkg.com/en/docs/cli/run for documentation about this command.
[0] yarn start exited with code 1```

## Environment ##

MacOS Catalina
❯ yarn -v
1.22.10
❯ node -v
v14.17.5

[GitHub PR Plugin] Entity overview page should show PR stats

There should be a widget on the Entity overview page which shows:

1. Total number of pull requests for the service, segmented by open and closed.
2. Average length of time that a PR is open for this service
3. Average size of a PR for this service

Implementation and look should be similar to the GithubActionsWidget.

[Security] Potential Secret Leak

It has been noticed that while using chromaui/action@v1 your projectToken 9tzak77m9nj is present in plaintext. Please ensure that secrets are encrypted or not passed as plain text in github workflows.

[Jenkins Plugin] Display builds in a list

Users of Jenkins should be able to use the Jenkins plugin to see lists of builds that have completed. This should work in a similar way to the Travis or Circle CI plugins.

Getting Started with Jenkins

Running Jenkins and logging in

Jenkins can be run locally using Docker. See: https://hub.docker.com/r/jenkins/jenkins

docker run -p 8080:8080 -p 50000:50000 -v jenkins_home:$(pwd)/jenkins_home jenkins/jenkins:lts

Visit http://localhost:8080 to see the jenkins UI and use it.

when Jenkins first starts up, you will be asked for an administrator password. You can find this in the jenkins logs where it is printed to STDOUT.

Jenkins will ask if you want to install common plugins. I'm not 100% certain if these are required or not. It might be best to install them just incase.

During setup, it will ask you to create an Admin user account. You can skip this and just continue to log in with the username admin and the password found in the logs.

Installing NodeJS

Follow the steps in this blog post to install NodeJS into Jenkins so we can run a build for a node project.

https://medium.com/@gustavo.guss/jenkins-starting-with-pipeline-doing-a-node-js-test-72c6057b67d4

Creating a build

The sample-service has a Jenkinsfile in the root of the project which will tell Jenkins how to build and test it.

To create a Jenkins pipeline for it, select "Create a Job".

Call the job, "sample-service", and make it a Multibranch Pipeline.

Give the job a display name, and point it at the source of the sample service in GitHub.

Once that is done, you should run and view some builds for the sample-service:

The Jenkins API

Docs for the API are available here. They are pretty awful. Once you get Jenkins started, more information will be available at http://localhost:8080/api/.

One section which is particularly important, but easy to overlook, is the information about "Controlling the amount of data you fetch". It describes how to use the tree query parameter to control the information returned by each endpoint. Understanding this is critical to understanding the Jenkins API.

Auth

Follow the steps in this Stack Overflow answer to get an API token.

Using the API

A list of builds for a specific job and branch can be accessed via the API with this curl command. The variables are:

1. <api-token> is the token we just generated
2. <job-name:sample-service> is the name of the job you created.
3. <branch-name> is the name of the GitHub branch to run tests for.

curl -g --user admin:<api-token> http://localhost:8080/job/<job-name:sample-service>/job/<branch-name>/api/json\?tree\=builds\[number,status,result\] | jq '.'

The fields returned by the API can be selected by changing the properties listed in the square brackets. [number,status,result]

It is possible to retrieve all builds for all branches of a job by using a complex tree parameter.

curl -g --user admin:<api-token> http://localhost:8080/job/sample-service/api/json?tree=jobs[name,builds[name,result]]

That returns something like this:

{
  "_class": "org.jenkinsci.plugins.workflow.multibranch.WorkflowMultiBranchProject",
  "jobs": [
    {
      "_class": "org.jenkinsci.plugins.workflow.job.WorkflowJob",
      "name": "master",
      "builds": [
        {
          "_class": "org.jenkinsci.plugins.workflow.job.WorkflowRun",
          "result": "SUCCESS"
        },
        {
          "_class": "org.jenkinsci.plugins.workflow.job.WorkflowRun",
          "result": "FAILURE"
        },
      ]
    }
  ]
}

Use the depth query parameter to explore the properties that the API makes available. For example, the following endpoint show most of the required information about builds which have run for the sample-service job.

http://localhost:8080/job/sample-service/api/json?depth=2

There is a JavaScript client for Jenkins available here: https://github.com/silas/node-jenkins. Please use it if it is helpful.

Design

Mockups are here: https://whimsical.com/2J9gPYGBT5ZvH4P5rqao7g

[Travis Plugin] End to end test

An end-to-end test will make it easier to confidently make changes to the plugin in the future. Instead of having to manually verify changes in the browser, the team could simply run the tests to have at least some confidence that the plugin works.

What the test should do

Phase 1

1. Load the plugin in the browser
2. Configure authentication and other settings for a Travis project
3. Verify that the builds show up

Tech choices

Using the real Travis API for this purpose would probably lead to some flakey tests so it would be best to mock the Travis API with the MSW library. This is the library the backstage team plan to use for mocking (source).

Please use cypress (https://www.cypress.io/) to write and run the tests.

[Plugin] PagerDuty - Display incidents

Build a basic PagerDuty plugin

Requirements

Create a basic PagerDuty plugin which can list and paginate incidents on the PagerDuty API. This should work similar to the Travis plugin except we are displaying incidents instead of builds.

Displaying incidents is just a first step. We will build on this with more abilities in the future.

Verification before starting

I am able to successfully access the https://api.pagerduty.com/incidents endpoint like this:

» curl -H 'Authorization: Token token=<api-token>' -H 'Accept: application/vnd.pagerduty+json;version=2' https://api.pagerduty.com/incidents\?time_zone\=UTC
» {"incidents":[],"limit":25,"offset":0,"total":null,"more":false}

I have added Roman as a manager in my PagerDuty account so he can create/view incidents and other PageDuty objects in the native interface.

References

1. PagerDuty REST API Overview
2. PagerDuty API Reference
3. Official NodeJS PagerDuty library.

TODO

• List incidents in the PagerDuty plugin
• Create an end-to-end test with a mock which tests that incidents can be displayed.

[GitHub PR Plugin] Entity page should show pull requests for that entity

The entity page should have a tab named "pull requests" which shows the pull requests for that specific service. It should look very similar to the /github-pull-requests page.

The owner and name of the repo to look up in the GitHub API can be found in the same way as the GitHub actions plugin is doing. The YAML file which describes each service has an annotation on it which stores the owner/name of the repo.

// plugins/catalog/src/components/EntityPage/EntityPage.tsx
{entity.metadata?.annotations?.[
  'backstage.io/github-actions-id'
] && (
  <Grid item sm={3}>
    <GithubActionsWidget entity={entity} branch="master" />
  </Grid>
)}

For example, here is the YAML metadata for the RoadieHQ/sample-service.

apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: sample-service
  annotations:
    backstage.io/github-actions-id: RoadieHQ/sample-service
spec:
  # omitted for brevity

One problem we will encounter is that the tabs implementation on the Entity Page doesn't really work. This tabs implementation should be improved as needed, and contributed upstream to Backstage.

[Travis Plugin] Display builds in list

Mockups are here: https://whimsical.com/KnT9oFQGNGCcy5rhp8Rp2n

Some comments:

1. The commit heading should link to that build in travis-ci.com
2. The search should be client side only - it should filter on commit heading, commit sha and branch name.
3. The two details are the length of time the build ran for, and the length of time ago that it ran.
4. There is a refresh button in the top right corner of the table to refresh the list of builds.
5. There should be pagination at the bottom

This page looks like this in Travis CI. My mockup attempts to stick pretty close to that.

The empty state of the list can simply explain to the user that there are no builds.

When a HTTP error occurs, it can be displayed near the top of the page just like the Circle CI plugin does.

TODO

• Show a basic list of builds in the UI with the information described in the mockup above.
• In a settings dialog, allow the user to specify their API token and the project they wish to view.
• Enable the build retry functionality. Clicking the icon on the right side of each build should re-run that build.
• Enable pagination
• Enable searching by commit heading, commit sha and branch name