Backstage's repo root: two workspaces, two stubbed CLI commands, and a bug bounty that is not the CNCF's

The Getting Started section is a link, not a command

Before installing anything, be clear about what you have cloned. The English README at the repository root opens with the project name, a row of badges, and one definition: an open source framework for building developer portals, powered by a centralized software catalog. From there it hands you off. The Getting Started section is a single sentence pointing at the getting started documentation, and the documentation list is a set of links to the main docs, the catalog page, an architecture overview with its decisions log, a design guide, and a Storybook for the UI components. No install command appears in the root file at all. The root manifest is named `root` and marked `"private": true`, which is the signature of a monorepo rather than an installable package. The repository is where the framework is developed; the portal you want is something you create from it.

yarn new replaced two CLI entry points with echo stubs

Two root scripts exist only to print a correction and exit:

"create-plugin": "echo \"use 'yarn new' instead\"",
"dev": "echo \"use 'yarn start' instead\""

Anything automated against `create-plugin` will appear to succeed while creating nothing, which is the worst shape of failure for a pipeline step. The real path is `yarn new`, and its defaults live in the `backstage` block of the same file, where new packages get `namePrefix: "@backstage/"` and `private: false`. That last value deserves a second look. A scaffolded package is publishable by default, so a scratch plugin written to try something out arrives carrying publish metadata from the moment it is generated. Either name it inside the `@backstage/` scope properly or keep throwaway experiments away from the scaffolder.

The two workspace globs decide what the framework can ship

The root manifest declares exactly two workspace globs:

"workspaces": [
  "packages/*",
  "plugins/*"
]

Everything the framework ships lives under those two paths, which is also where community plugins are expected to land. Build and clean are delegated to the same CLI tool:

"build:all": "backstage-cli repo build --all",
"clean": "backstage-cli repo clean"

So is the release path, and it is not local:

"fix": "backstage-cli repo fix --publish"

Read that `--publish` flag twice. A repository-wide fix run prepares version bumps and publish steps across every workspace, which means a local tidy-up and a release preparation are the same command separated by one argument. For a contributor that is a sharp edge worth knowing about before the first run.

Security disclosure points at Spotify's bounty program

The Security section routes sensitive reports away from the repository and toward a different company's program. It asks that sensitive security issues be reported through Spotify's bug-bounty program rather than GitHub, and it points at a SECURITY.md file for the complete security release process. This is history showing through the process: Backstage was created by Spotify and is now hosted by the Cloud Native Computing Foundation as an Incubation level project, so the code sits under CNCF while the disclosure channel is still the original sponsor's. An organization whose policy names a project-run or CNCF security contact will not find one in this repository. Sorting out whether that program covers a flaw in a plugin you operate is a question to answer before you deploy, not after.

Five translated READMEs sit beside the English one

The root carries the same introduction in five languages, with Korean, Simplified Chinese, French, and Japanese linked from a language switcher at the top of the English file. Nothing else in the repository is translated. Feature pages, the architecture overview, the decisions log, the design guide, and the FAQ all live on the documentation site, and the component Storybook is served separately. So those four files are the only translated artifacts, and they are introductions rather than instructions. A team working in one of those languages gets the argument for the framework in its own language and then reads the setup path in English. For a project whose adoption work is documentation, that asymmetry is worth knowing before you plan a rollout.

Prerelease tags ship alongside patch releases, sometimes the same day

The cadence is readable from the tag list alone. v1.55.2 landed on 2026-09-25, v1.55.3 on 2026-09-29, and v1.56.0-next.1 also on 2026-09-29, with that prerelease string sitting in the root manifest as the project version. The last push to the master branch is dated 2026-09-29, and the repository is not archived. Two consequences follow for anyone pinning dependencies. Patch releases move within days, so an unpinned range is a moving target. And because the prerelease sits in the same tag stream, any resolution that accepts prereleases can pull a 1.56.0-next build into an environment you believed was on 1.55.x. The root directory also carries a `.changeset` directory, an OWNERS file, a DCO, and a label definitions file, all sitting next to the review guidelines and the code of conduct.

What ships in the box is a catalog, a scaffolder, and a docs tool

Three pieces are described as included out of the box. The Software Catalog manages the software you already have, and the description names microservices, libraries, data pipelines, websites, and ML models as the kinds of entities it holds. Software Templates spin up new projects and standardize tooling on your organization's practices. TechDocs makes technical documentation easier to create, maintain, find, and use, with a docs like code approach. Past those three, everything else is an open source plugin from the plugins directory, described as a growing ecosystem. The claim is that Backstage unifies infrastructure tooling, services, and documentation into one development environment without product teams giving up autonomy. What it does not include is a portal: navigation, identity, administration, and search are decisions you make by choosing plugins. Treat the first three as a starting inventory, not a finished product.

The API report gate runs with an 8GB heap and a four-name allowlist

One script shows how deliberately the public surface is policed:

"build:api-reports:only": "LANG=en_US.UTF-8 NODE_OPTIONS=--max-old-space-size=8192 backstage-repo-tools api-reports --sql-reports --allow-warnings 'packages/backend-app-api,packages/core-components,plugins/+(catalog|catalog-import|kubernetes)' -o ae-undocumented,ae-wrong-input-file-type --validate-release-tags"

It runs with an 8GB maximum old space size, writes reports, and tolerates warnings in four named places only. Everything else is expected to stay documented and carry a release tag. For a consumer that means a new export in an unnamed workspace fails the gate, which is the intended behavior, and it also means the surface is a choice somebody maintains on purpose rather than something that drifts. The same root directory holds a knexfile for database migrations, a Lighthouse config with its own CI directory, a Playwright config, a Vale style file, and a typos configuration, so a single change has to survive format, spelling, browser, and performance checks.

Editorial conclusion

Backstage fits organizations with many services and one catalog to feed, and it charges them a plugin selection, a database, and an upgrade stream that moves every few days. Do not adopt it for a handful of services, and do not expect a finished portal on day one. Before committing, read the architecture decisions page, check whether the disclosure channel in SECURITY.md satisfies your organization's reporting policy, and read the release notes for the version range you plan to pin.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes