Get Roadie in your IDE with our new MCP Servers
Roadie
← Backstage Plugins Guides
Cloudsmith logo

Backstage Cloudsmith Plugin

Created by Roadie

Cloudsmith is a managed artifact repository service. It hosts packages and images in private or public repositories. Each repository belongs to an owner and has a repo name. Teams use it to store and deliver the software they build.

The Cloudsmith plugin brings those repositories into Backstage. It adds cards to your portal that show key stats for a repository. You can see usage against limits for bandwidth and storage. You can review a list of packages in a repo. You can read recent audit events from the repository. You can view security scan results for packages with known issues. This information sits in the same place your engineers already use every day.

Typical use cases are simple. Gain quick visibility into what is in a repo. Keep an eye on consumption before you hit limits. Track changes that matter for compliance. Surface vulnerable packages early so teams can act. Give service owners a shared view of artifacts linked to their components in the catalog.

If you run Backstage yourself this plugin helps connect your portal to the artifacts that power your systems. It reduces context switching. It makes routine checks faster. It gives teams the context they need without extra steps.

A screenshot of Cloudsmith plugin showing 4 components in more detail.

Installation Instructions

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

Install the frontend package

  1. Add the Cloudsmith plugin to the frontend app
Copy 
yarn add --cwd packages/app @roadiehq/backstage-plugin-cloudsmith

Add the cards to the Home page

  1. Open this file
Copy 
packages/app/src/components/home/Homepage.tsx
  1. Import the cards
Copy 
import {
  CloudsmithStatsCard,
  CloudsmithQuotaCard,
  CloudsmithRepositoryAuditLogCard,
  CloudsmithRepositorySecurityCard,
  CloudsmithPackageListCard,
} from '@roadiehq/backstage-plugin-cloudsmith';
  1. Render the cards on the page
Copy 
// example layout using Material UI Grid
// place inside your homepage component render
<Grid container spacing={3}>
  <Grid item xs={12} md={6}>
    <CloudsmithStatsCard repo="repo-name" owner="org-name" />
  </Grid>

  <Grid item xs={12} md={6}>
    <CloudsmithQuotaCard owner="org-name" />
  </Grid>

  <Grid item xs={12} md={6}>
    <CloudsmithRepositoryAuditLogCard owner="org-name" repo="repo-name" />
  </Grid>

  <Grid item xs={12} md={6}>
    <CloudsmithRepositorySecurityCard owner="org-name" repo="repo-name" />
  </Grid>

  <Grid item xs={12}>
    <CloudsmithPackageListCard owner="org-name" repo="repo-name" />
  </Grid>
</Grid>

Use your Cloudsmith org as owner
Use your Cloudsmith repository as repo

You will need a Cloudsmith API key

Configure the backend proxy in app config

  1. Add this to your app config
Copy 
# app-config.yaml
proxy:
  '/cloudsmith':
    target: 'https://api.cloudsmith.io/v1'
    headers:
      X-Api-Key: ${CLOUDSMITH_API_KEY}
      User-Agent: 'Backstage'

Provide the Cloudsmith API key

Set the environment variable for the backend process

Copy 
# bash or zsh
export CLOUDSMITH_API_KEY=your_api_key_here
Copy 
# PowerShell
setx CLOUDSMITH_API_KEY "your_api_key_here"

Restart the backend after setting the variable

Legacy backend system

Most legacy Backstage backends already include the proxy backend plugin
If your app removed it, add it back

  1. Install the backend proxy plugin
Copy 
yarn add --cwd packages/backend @backstage/plugin-proxy-backend
  1. Create the proxy plugin module file if missing
Copy 
// packages/backend/src/plugins/proxy.ts
import { createRouter } from '@backstage/plugin-proxy-backend';
import { PluginEnvironment } from '../types';

export default async function createPlugin(env: PluginEnvironment) {
  return await createRouter({
    logger: env.logger,
    config: env.config,
    discovery: env.discovery,
  });
}
  1. Wire it in your backend index if missing
Copy 
// packages/backend/src/index.ts
import proxy from './plugins/proxy';

// inside the main function after creating the service builder
// const logger = ...
// const config = ...
// const discovery = ...
// const router = await proxy({ logger, config, discovery });

// app.use('/api/proxy', await proxy({ logger, config, discovery }));

Make sure the app config proxy block from above is present
That is what forwards calls to Cloudsmith

New backend system

If you use the new backend system you must add the proxy plugin to the backend builder

  1. Install the backend proxy plugin
Copy 
yarn add --cwd packages/backend @backstage/plugin-proxy-backend
  1. Register the proxy plugin in the backend entry
Copy 
// packages/backend/src/index.ts
import { createBackend } from '@backstage/backend-defaults';
import { proxyPlugin } from '@backstage/plugin-proxy-backend';

const backend = createBackend();
backend.add(proxyPlugin());
backend.start();

The app config proxy block from above is still required

Run the app

Start the backend in one terminal

Copy 
yarn workspace backend start

Start the frontend in another terminal

Copy 
yarn workspace app start

You should see the Cloudsmith cards on the home page once the app loads

Changelog

This changelog is produced from commits made to the Cloudsmith 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.

Dependency updates

  • Upgrade to version 1.40 #1952 merged 2 months ago
  • Revert a previous dependency bump #1825 merged 7 months ago
  • Update Backstage dependencies #1821 merged 7 months ago
  • Update Backstage package versions #1728 merged 10 months ago
  • Update Backstage dependencies #1684 merged 11 months ago

Maintenance

  • Remove unused plugin dependencies #1847 merged 7 months ago

Set up Backstage in minutes with Roadie

Get a demo