Demo Integrations Private Repository

In this guide, you’ll learn how to configure Backstage to pull catalog entities from a private GitHub repository. We’ll cover:

1. Making a repo private
2. Reviewing the catalog-info.yaml definition
3. Registering a component (and troubleshooting 404 errors)
4. Setting up a GitHub integration with a Personal Access Token (PAT)
5. Generating and securing a PAT
6. Restarting Backstage and importing the entity
7. Viewing your newly imported component

1. Convert Your Repository to Private

Start with your Backstage example repo (e.g., backstage-auth-service) in a public state:

Steps:

1. Go to Settings → Options → Change repository visibility.
2. Choose Private, confirm, and authenticate if prompted.

Once done, your repo is no longer publicly accessible.

2. Review the Catalog Definition

Ensure your catalog-info.yaml defines both a Component and an API:

apiVersion: backstage.io/v1beta1
kind: Component
metadata:
  name: auth-service
  description: authentication service
  tags:
    - javascript
  links:
    - url: https://google.com
      title: Admin Dashboard
      icon: dashboard
      target: admin-dashboard
spec:
  type: service
  lifecycle: production
  owner: guests
  providesApis:
    - auth-api
---
apiVersion: backstage.io/v1alpha1
kind: API
metadata:
  name: auth-api
  description: Verify user authentication status
spec:
  type: openapi
  lifecycle: production
  owner: guests
  apiProvidedBy: auth-service

Copy the raw URL to this file (for example:
https://raw.githubusercontent.com/<user>/backstage-auth-service/main/catalog-info.yaml)
—you’ll use it to register the location in Backstage.

3. Attempt to Register the Component

Run the Backstage CLI command to register the existing catalog-info.yaml location:

backstage-cli register-location \
  --location "url:https://raw.githubusercontent.com/<user>/backstage-auth-service/main/catalog-info.yaml"

Because the repo is private, you’ll see a 404 error:

{
  "error": {
    "name": "InputError",
    "message": "NotFoundError: Request failed for https://raw.githubusercontent.com/<user>/backstage-auth-service/main/catalog-info.yaml: 404 Not Found",
    "stack": "..."
  }
}

4. Configure the GitHub Integration

Edit your app-config.yaml to allow reading from GitHub and provide your PAT via an environment variable:

# app-config.yaml
reading:
  allow:
    - host: 'raw.githubusercontent.com'

integrations:
  github:
    - host: github.com
      token: ${GITHUB_TOKEN}
      # For GitHub Enterprise use:
      # apiBaseUrl: https://ghe.example.net/api/v3
      # rawBaseUrl: https://ghe.example.net/raw
      # token: ${GHE_TOKEN}

Table: GitHub Integration Settings

4.1 Set the Environment Variable

After generating your PAT, export it in your shell:

export GITHUB_TOKEN=<your_personal_access_token>

Or—for demo purposes—embed it (not recommended for production):

integrations:
  github:
    - host: github.com
      token: ghp_XXXXXXXXXXXXXXXXXXXXXXXXXXXX

5. Generate a GitHub Personal Access Token

1. Navigate to Settings → Developer settings → Personal access tokens → Tokens (classic) → Generate new token (classic).
2. Enter a name and expiration, then check the repo scope to allow reading private repos.
3. Click Generate token and copy the token immediately.

GitHub will show the token only once:

Table: PAT Scopes for Private Repo Access

6. Restart Backstage and Import the Component

Save your config changes, ensure GITHUB_TOKEN is exported, and restart the dev server:

yarn dev

In the Backstage UI, navigate to Create → Import Existing Component, paste your raw URL, and click Review. Backstage will authenticate using your PAT and fetch the entity:

Click Import to complete the registration.

7. View the Imported Component

Head over to the Catalog in Backstage, select auth-service, and explore its overview, description, and relationships:

You’ve now configured Backstage to successfully fetch catalog entities from a private GitHub repository!

Links and References

• Backstage Catalog Overview
• GitHub Docs: Personal Access Tokens
• Backstage Configuration Reference