Backstage_Plugin_Github_Integration_Dev.playbook.md

Playbook: Creating a GitHub Integration Plugin for Backstage

Overview

This playbook outlines the steps to create a plugin for Backstage that integrates with GitHub to do user specified tasks.

What's Needed From User

• GitHub repository URL.
• Access token with appropriate permissions for accessing the repository.

Procedure

1. Setup Backstage Plugin

• Infer the name of the plugin from the task or feature request from the provided prompt as <use-case>.
• Navigate to the root directory of the Backstage project already set up and present in the home directory or provided by the user.
• Run yarn new --select plugin command to create a new plugin named <use-case>.
• Ask user to provide the GitHub repository URL and access token if not already provided.
• Update the app-config.yml file with the GitHub access token by adding the following:

integrations:
  github:
    - host: github.com
      token: <github-access-token>

2. Implement Components

• Navigate to the created directory inside plugins (plugins/<use-case>).
• Remove the existing components inside the plugins/<use-case>/src/components directory.
• Create a new component folder inside components components/<use-case>.
• create a new component index.tsx inside components/<use-case>.
• Use api.github.com/repos/<owner>/<repo>/<use-case> to fetch data from the GitHub API.
• Implement the plugin-specified features using React without githubAuthApi or github oAuth use github token directly.
• Add necessary hooks for fetching data from the GitHub API in the plugins/<use-case>/src/hooks directory.
• Add necessary utility funtions in the plugins/<use-case>/src/utils directory.

3. Update the Plugin

• Update the src/routes.ts with plugin-id
• Update the src/plugin.ts with the component import and plugin-id.
• Update the src/index.ts with the plugin import.
• Update the src/types.ts directory with the necessary components.

4. Register the Component

• Open the dev/index.ts file in the plugin directory.
• Import and register the <use-case> component:

5. Update the Backend

• Add necessary changes in the packages/backend/src/plugins/catalog.ts file.
• Update other necessary files in the backend to support the plugin.

6. Update Main App File

• Update the App.tsx file in the packages/app/src directory.
• Import the <use-case> component and add it to the App.tsx file.
• Create a new route for the <use-case> component in the routes function.

7. Import the plugin and update packages

• Import and update the plugin in the packages/app/src/components/catalog/EntityPage.tsx file.
• Import and update the plugin in the packages/app/src/components/Root/Root.tsx file.
• Import and update the plugin in the packages/app/src/components/Search/SearchPage.tsx file.

8. Test the Plugin

• Stop any running Backstage development servers.
• Start the Backstage development server by running yarn dev.
• Check for the plugin on the catalog page.
• Navigate to the <ngrok-frontend-url>/<use-case> endpoint in the browser to test the plugin.
• Ignore the Invalid Host/Origin header error in the browser console.
• Ignore the 101 ws error on the ngrok backend terminal.

9. Readme for User

• Update the README.md file in the plugin directory with the following steps:
  • Instructions to create a new plugin.
  • Details on implementing the component.
  • Any other necessary steps or changes needed by the user.

Advice and Pointers

• Do not change port 3000 and port 7007 in the app-config.yaml file.
• Never Create a fresh Backstage project for the plugin.
• Do not change the ports in the app-config.yml file of 3000 and 7007.
• Ignore the Invalid Host/Origin header error in the browser console.
• Ignore the 101 ws error on the ngrok backend terminal.
• No need for github oAuth app clientID and client secret for the plugin use github token directly.
• No need for a backend Secret
• Never restart currently running ngrok tunnels.
• Follow the latest react and backstage conventions for creating components https://react.dev/blog/2023/03/16/introducing-react-dev
• Ensure that the access token used for GitHub integration has appropriate permissions.
• Do not use React.FC for any components.
• Do not push anything on Git Hub.
• Keep the plugin structure organized and follow best practices.
• Utilize TypeScript for type safety and better development experience.
• Document any additional features or configurations provided by the plugin.
• Never Create a fresh Backstage project for the plugin.