Backstage GitHub Integration
You set up a backstage github integration by linking a GitHub App or personal token to your developer portal. This link lets the portal read code repos, team lists, and software templates from your version control system. Platform teams often start with a single shared token to get the catalog running fast. When that token has broad write permissions, any portal user or template can change production code. How a backstage github integration works A developer portal needs steady read and write
GitHub Actions Security + Backstage Security Plugins: the complete guide
Architecture patterns, implementation strategies, and security best practices. Delivered to your inbox.
You set up a backstage github integration by linking a GitHub App or personal token to your developer portal. This link lets the portal read code repos, team lists, and software templates from your version control system. Platform teams often start with a single shared token to get the catalog running fast. When that token has broad write permissions, any portal user or template can change production code.
How a backstage github integration works
A developer portal needs steady read and write paths to your source code host. The portal reads catalog files from repos to build an index of your services. It also reads user and team profiles so portal roles match your company directory. When engineers create a new service, the portal writes starter files into a fresh repo.
You can link the two systems with a personal token or a GitHub App. Personal tokens tie the portal to one human account and share that user's full reach. A GitHub App is a better choice for teams because it acts as its own service identity. You grant the app specific read or write rules on selected repos.
Once you add the app credentials to your portal settings, background jobs start syncing data. These jobs run on a timer to check for new services, updated docs, and team changes. The portal stores this data in its own database so pages load fast for your engineers.
Choosing between personal tokens and apps
Personal tokens are fast to create during a quick test on a laptop. Still, they break when the owner leaves the company or changes team roles. They also share rate limits with every other script that uses the same human account. One busy catalog sync can block other build tools from reading code.
GitHub Apps give you separate rate limits that scale with the size of your company. They also let you separate read rules for the catalog from write rules for software templates. You can give the catalog reader access to all repos while keeping template write rules narrow. Even so, the app credentials still sit inside your portal server memory.
GitHub Actions Security + Backstage Security Plugins: architecture patterns and best practices
Continue reading? Get the full guide.
Free. No spam. Unsubscribe anytime.
What native setup solves and where gaps remain
Using a dedicated GitHub App solves account lockouts and basic permission scoping at the repo level. You no longer rely on one engineer's login to keep your internal catalog alive. You can also see in your code host logs that the portal app made a change.
The main gap is that repo permissions only decide which app can log in. They do not inspect what individual database queries, shell commands, or API calls do in flight. When developers use the portal to run backend tasks or query data, the portal uses shared credentials. GitHub logs show the portal app identity rather than the specific engineer who clicked the button.
This shared identity makes audits hard when a template or plugin runs a risky action. If a portal job queries a database, raw emails or card numbers can return in the output. Native code host roles cannot rewrite matched fields in results or pause a single risky command for review.
Check database and API queries on the wire
Identity tools, roles, and network rules decide who opens a session. Setup alone cannot check what each query does or mask sensitive values in a response once a session starts. When workflows touch Postgres, MySQL, SQL Server, MongoDB, ClickHouse, Kubernetes APIs, SSH, or internal HTTP APIs, hoop.dev runs beside those services as an open-source proxy, a sidecar for your Postgres or API. It inspects requests coming in and results going back on the wire.
Your login details and client tools stay as they are while hoop.dev guardrails refuse bad deletes or drops before they run. On responses, hoop.dev data masking rewrites matched sensitive values in memory. Furthermore, hoop.dev holds SOC 2 Type II, is MIT licensed, and writes every query and decision to an audit trail that generates evidence for HIPAA, GDPR, and PCI DSS. See the source on GitHub.
Frequently asked questions
Should I use a GitHub App or a personal token for my portal?
Use a GitHub App for shared team portals. It stays active when staff leave, gives you higher API rate limits, and lets you scope repo rules.
Why do my new repositories not show up in the software catalog right away?
The portal reads repo lists on a background schedule unless you set up event webhooks. Check that your GitHub App has permission to read the new repo and wait for the next sync cycle.
How do I limit the blast radius of software templates that create repositories?
Grant write rules only to the specific code groups where new services belong. Do not give your template runner write access to core system repos or production config folders.