@adityasinghal26/plugin-github-codespaces
v1.0.4
Published
Interact with your GitHub Codespaces directly from Backstage platform.
Downloads
1,180
Maintainers
Readme
GitHub Codespaces Plugin
Interact with your GitHub Codespaces directly from Backstage platform.
GitHub Codespaces enable you to create a Devcontainer from your GitHub repository and get in Development mode right away. For more documentation, visit below documentation. You can also view your codespaces by following the website link below after logging in to GitHub.
Documentation: https://docs.github.com/en/codespaces
Website: https://github.com/codespaces
Features
- Authenticate the user with Github (with 'repo' and 'codespace' permissions)
- List all the codespaces for authenticated user
- List codespaces in a project repository for authenticated user
- List codespaces with display name as entity name for authenticated user
- Create/Start a new codespace for an entity (with display name as entity name)
- Pagination for codespaces
Screenshots
- GitHub Codespaces Menu
- Start Codespaces Widget
- Start and List Codespaces Card
- List Codespaces Content (filtered for Entity)
- List Codespaces Content (filtered for Project Repository)
Setup
Generic Requirements
Provide OAuth credentials:
- Create an OAuth App in the GitHub organization with the callback URL set to
http://localhost:7007/api/auth/github/handler/frame
. - Take the Client ID and Client Secret from the newly created app's settings page and put them into
AUTH_GITHUB_CLIENT_ID
andAUTH_GITHUB_CLIENT_SECRET
environment variables.
- Create an OAuth App in the GitHub organization with the callback URL set to
Annotate your component with a correct GitHub Actions repository and owner:
The annotation key is
github.com/project-slug
.Example:
apiVersion: backstage.io/v1alpha1 kind: Component metadata: name: backstage description: backstage.io annotations: github.com/project-slug: 'backstage/backstage' # Add below annotation for a custom devcontainer configuration with # relative path of devcontainer.json file from root of the repository github.com/devcontainer-path: .devcontainer/devcontainer.json spec: type: website lifecycle: production owner: user:guest
Standalone app requirements
- Install the plugin dependency in your Backstage app package:
# From your Backstage root directory
yarn add --cwd packages/app @adityasinghal26/plugin-github-codespaces
- Add to the app
EntityPage
component:
// In packages/app/src/components/catalog/EntityPage.tsx
import {
EntityGithubCodespacesWidget,
EntityGithubCodespacesCard,
EntityGithubCodespacesContent,
EntityGithubCodespacesRepoContent
isGithubCodespacesAvailable,
} from '@adityasinghal26/plugin-github-codespaces';
// Create the codespaces tab content for Github Codespaces
const codespacesContent = (
<>
{/* Add this entity switch to view the list
of codespaces filtered with entity name */}
<EntitySwitch>
<EntitySwitch.Case if={isGithubCodespacesAvailable}>
<Grid item xs={12}>
<EntityGithubCodespacesContent />
</Grid>
</EntitySwitch.Case>
</EntitySwitch>
{/* Add this entity switch to view the list
of codespaces filtered with repository */}
<EntitySwitch>
<EntitySwitch.Case if={isGithubCodespacesAvailable}>
<Grid item xs={12}>
<EntityGithubCodespacesRepoContent />
</Grid>
</EntitySwitch.Case>
</EntitySwitch>
</>
);
// You can add the overview widget and card to overviewContent as below
// this overview content can be used any number of pages
const overviewContent = (
<Grid container spacing={3} alignItems="stretch">
{/* other grids... */}
{/* Add this entity switch to add the Start Codespace widget */}
<EntitySwitch>
<EntitySwitch.Case if={e => Boolean(isGithubCodespacesAvailable(e))}>
<Grid item md={6} xs={12}>
<EntityGithubCodespacesWidget />
</Grid>
</EntitySwitch.Case>
</EntitySwitch>
{/* Add this entity switch to add the Start and List Codespace card.
You can set enableStart as 'true' to show the Start Codespace button.
If left unset or set as 'false', the Start Codespace button will be unavailable. */}
<EntitySwitch>
<EntitySwitch.Case if={e => Boolean(isGithubCodespacesAvailable(e))}>
<Grid item md={6} xs={12}>
<EntityGithubCodespacesCard enableStart={true} />
</Grid>
</EntitySwitch.Case>
</EntitySwitch>
</Grid>
);
// You can add the tab to any number of pages, the service page is shown as an
// example here
const serviceEntityPage = (
<EntityLayout>
{/* other tabs... */}
<EntityLayout.Route
if={isGithubCodespacesAvailable}
path="/github-codespaces"
title="GitHub Codespaces">
{codespacesContent}
</EntityLayout.Route>
- Run the app with
yarn start
and the backend withyarn start-backend
. Then navigate to/github-codespaces/
under any entity.
App menu requirements
Make sure that the required package is installed as in above section step #1.
- Add to the app
App.tsx
component:
// In packages/app/src/App.tsx
import { GithubCodespacesPage } from '@adityasinghal26/plugin-github-codespaces';
// Add the route to the App path routes
const routes = (
<FlatRoutes>
{/* other routes here */}
<Route path="/github-codespaces" element={<GithubCodespacesPage />} />
</FlatRoutes>
);
- Add to the app
Root.tsx
component:
// In packages/app/src/components/Root/App.tsx
import { GitHubIcon } from '@backstage/core-components';
import { GithubCodespacesPage } from '@adityasinghal26/plugin-github-codespaces';
// Add the menu to the Root menu sidebar
export const Root = ({ children }: PropsWithChildren<{}>) => (
<SidebarPage>
<Sidebar>
{/* other sidebar items here */}
{/* add inside "Menu" SidebarGroup */}
<SidebarItem icon={GitHubIcon} to="github-codespaces" text="Codespaces" />
{/* other sidebar items here */}
</Sidebar>
{children}
</SidebarPage>
);
Limitations
- Any codespace started using EntityGithubCodespacesWidget or EntityGithubCodespacesCard action will create a new codespace with the exact same display name as the entity name.
- Once the codespace is created, you can only start the Codespace from the Widget/Card action.
- The plugin does not support GitHub Enterprise yet. The feature will be extended in the next releases.