@coder/backstage-plugin-coder

Integrate Coder Workspaces into Backstage

Create and manage Coder workspaces from Backstage.

Screenshots

Features

• Users link their Coder accounts with Backstage via tokens
• Associate Coder workspaces with catalog items in Backstage
• Workspace list component for viewing and managing workspaces

Setup

This assumes you already have a Coder deployment running. Replace https://coder.example.com with your Coder deployment access URL. This also assumes you have a template that has a parameter for a git repository URL (e.g. git_repo_url) that auto-clones the repository or uses envbuilder to build the Dev Container.

• If you have a standalone Backstage app (you didn't clone this repo), then do

  yarn --cwd packages/app add @coder/backstage-plugin-coder
  

• Add the proxy key to your app-config.yaml:

  proxy:
    endpoints:
      '/coder':
        # Replace with your Coder deployment access URL (add a trailing slash)
        target: 'https://coder.example.com/'
  
        changeOrigin: true
        allowedMethods: ['GET'] # Additional methods will be supported soon!
        allowedHeaders: ['Authorization', 'Coder-Session-Token']
        headers:
          X-Custom-Source: backstage
  

• Add the CoderProvider to the application:

  // packages/app/src/App.tsx
  
  import {
    type CoderAppConfig,
    CoderProvider,
  } from '@coder/backstage-plugin-coder';
  
  const appConfig: CoderAppConfig = {
    deployment: {
      accessUrl: 'https://coder.example.com',
    },
  
    // Set the default template (and parameters) for
    // catalog items. Individual properties can be overridden
    // by a repo's catalog-info.yaml file
    workspaces: {
      defaultTemplateName: 'devcontainers',
      defaultMode: 'manual',
  
      // This property defines which parameters in your Coder
      // workspace templates are used to store repository links
      repoUrlParamKeys: ['custom_repo', 'repo_url'],
  
      params: {
        repo: 'custom',
        region: 'eu-helsinki',
      },
    },
  };
  
  // ...
  
  export default app.createRoot(
    <CoderProvider appConfig={appConfig}>
      <AlertDisplay />
      <OAuthRequestDialog />
      <AppRouter>
        <Root>{routes}</Root>
      </AppRouter>
    </CoderProvider>,
  );
  

  Note: You can also wrap a single page or component with CoderProvider if you only need Coder in a specific part of your app. See our API reference (particularly the section on the CoderProvider component) for more details.

• Add the CoderWorkspacesCard card to the entity page in your app:

  // packages/app/src/components/catalog/EntityPage.tsx
  
  import { CoderWorkspacesCard } from '@coder/backstage-plugin-coder';
  
  // We recommend placing the component inside of overviewContent
  const overviewContent = (
    <Grid container spacing={3} alignItems="stretch">
      {entityWarningContent}
      <Grid item md={6}>
        <EntityAboutCard variant="gridItem" />
      </Grid>
  
      {/* Coder component should go inside Grid to help it work with MUI layouts */}
      <Grid item md={6} xs={12}>
        <CoderWorkspacesCard readEntityData />
      </Grid>
  
      {/* Other elements for overviewContent go here */}
    </Grid>
  );
  

app-config.yaml files

In addition to the above, you can define additional properties on your specific repo's catalog-info.yaml file.

Example:

apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: python-project
spec:
  type: other
  lifecycle: unknown
  owner: pms

  # Properties for the Coder plugin are placed here
  coder:
    templateName: 'devcontainers'
    mode: 'auto'
    params:
      repo: 'custom'
      region: 'us-pittsburgh'

You can find more information about what properties are available (and how they're applied) in our catalog-info.yaml file documentation.

Roadmap

This plugin is in active development. The following features are planned:

• Example component using the Coder API to make authenticated requests on behalf of the user
• Add support for only rendering component if catalog-info.yaml indicates the item is compatible with Coder
• OAuth support (vs. token auth) for linking Coder accounts
• "Open in Coder" button/card component for catalog items
• Example creating workspaces with Backstage Scaffolder
• Example dedicated "Coder" page in Backstage

Contributing

This plugin is part of the Backstage community. We welcome contributions!