@coder/backstage-plugin-devcontainers-backend

Automatically tag your repos that support Dev Containers

Automatically detect development containers (Dev Container) files in your repositories on GitHub/GitLab/Bitbucket, and have Backstage automatically tag them in the background!

Screenshots

Features

Note: While this plugin can be used standalone, it has been designed to be a backend companion to backstage-plugin-devcontainers-react.

Standalone features

• Automatically tag repos from GitHub/GitLab/Bitbucket that contain a devcontainer.json file
  • Repos are tagged as part of Backstage's processing loop

When combined with the frontend plugin

• Provides an end-to-end solution for automatically adding/removing Dev Containers metadata in your Backstage installation, while letting you read them from custom hooks and components

Setup

[!WARNING] All setup instructions assume you are using a Backstage deployment created with @backstage/create-app version 0.5.10 or earlier. Any later versions may or may not use Backstage's New Backend System (described here and here). We are currently evaluating how best to support the new system.

Before you begin

Ensure that you have the following ready to go:

• A Backstage deployment that you can modify
• A GitHub/GitLab/Bitbucket repository that contains a devcontainers.json metadata file. VS Code has a quick-start guide for adding Dev Containers to a repo.

Note: While this plugin has been developed and published by Coder, no Coder installations are required.

Installation

1. From your Backstage deployment, run the following command:

   yarn --cwd packages/backend add @coder/backstage-plugin-devcontainers-backend

2. Navigate to the backend/src/plugins/catalog.ts file (this file should automatically be created for you through @backstage/create-app)

3. Import your source control manager provider of choice (Backstage has built-in support for GitHub, GitLab, and Bitbucket)

   export default async function createPlugin(
     env: PluginEnvironment,
   ): Promise<Router> {
     const builder = await CatalogBuilder.create(env);
     builder.addEntityProvider(
       GithubOrgEntityProvider.fromConfig(env.config, {
         id: 'production',
         orgUrl: 'https://github.com/coder',
         logger: env.logger,
         schedule: env.scheduler.createScheduledTaskRunner({
           frequency: { minutes: 60 },
           timeout: { minutes: 15 },
         }),
       }),
     );
   
     // Rest of implementation
   }

4. Import the DevcontainersProcessor class, and register it with your plugin creator:

   export default async function createPlugin(
     env: PluginEnvironment,
   ): Promise<Router> {
     const builder = await CatalogBuilder.create(env);
     builder.addEntityProvider(/* GitHub setup */);
   
     builder.addProcessor(
       DevcontainersProcessor.fromConfig(env.config, {
         tagName: 'example', // Defaults to devcontainers
         logger: env.logger,
         eraseTags: false,
       }),
     );
   
     // Add any extra processors and handle setup here
   }

5. As your provider of choice re-validates data and emits more entity information, DevcontainersProcessor will automatically intercept the data and append or remove tags, based on whether the current repository has a Dev Containers file! (See our API docs for more info on our appending/removal process)

Full example:

// catalog.ts
import { DevcontainersProcessor } from '@coder/backstage-plugin-devcontainers-backend';

export default async function createPlugin(
  env: PluginEnvironment,
): Promise<Router> {
  const builder = await CatalogBuilder.create(env);
  builder.addEntityProvider(
    GithubOrgEntityProvider.fromConfig(env.config, {
      id: 'production',
      orgUrl: 'https://github.com/coder',
      logger: env.logger,
      schedule: env.scheduler.createScheduledTaskRunner({
        frequency: { minutes: 60 },
        timeout: { minutes: 15 },
      }),
    }),
  );

  // ScaffolderEntitiesProcessor is one of the processors automatically
  // added to a newly-scaffolded application
  builder.addProcessor(new ScaffolderEntitiesProcessor());

  builder.addProcessor(
    DevcontainersProcessor.fromConfig(env.config, {
      logger: env.logger,
      eraseTags: false,
    }),
  );

  const { processingEngine, router } = await builder.build();
  await processingEngine.start();
  return router;
}

Limitations

Search limitations

This plugin lets the user decide how to bring in repository data. As such, the plugin is limited by (1) what data your Backstage repo provider is able to detect, and (2) what API calls your source control manager supports.

Basic Dev Containers support has been tested for GitHub, GitLab, and Bitbucket, using their default Backstage data providers. All three are able to detect a Dev Container config file, as long as the file is located in a supported location, as defined by the official Dev Containers specification.

Other providers can be used, but are not guaranteed to work out of the box. In addition, not all source control managers provide an API for searching for deeply-nested files. In some cases, only the first two Dev Container config locations will be detectable.

We are happy to expand support for other source control managers, though. If you have a specific use case you'd like our help with, feel free to open a new issue!

VS Code limitations

At present, the official Visual Studio Remote Development extensions do not support branches other than /tree/main. As such, trying to open a VS Code link that is configured with a non-main branch may error out. Please see Microsoft's open issue for expanding support.

API documentation

Please see the directory for our API references for additional information.

Contributing

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