How the IDP works#
Concepts and architecture behind SKAO’s Backstage-based Internal Developer Platform.
Why SKAO built an IDP#
Before the IDP, finding out who owned a repository, what it depended on, or how to start a new project meant searching GitLab directly or asking around. Backstage centralises that: a software catalog gives every GitLab project, group, and user a browsable entity, and the scaffolder turns “create a new SKAO service” into a guided form instead of a checklist of manual GitLab configuration steps.
Deployment#
The IDP runs on the official Backstage Helm chart, deployed to the same production services-eks cluster (AWS eu-west-2) that hosts the CARs (Nexus and Harbor). It uses a dedicated Postgres RDS instance — GitLab OAuth credentials, the catalog PAT, and the database connection string are all injected via Vault.
The IDP’s own container image is published to artefact.skao.int. See Central Artefact Repositories for how that publishing path works.
How the catalog is populated#
The catalog is entirely GitLab-sourced. A GitLab org provider scans the ska-telescope/ska-dev group on a 30-minute schedule and ingests its groups and users as catalog Group and User entities. Sign-in is restricted to members of that group, and only entities the provider’s rules allow — Group and User — are ingested this way.
This means the catalog reflects GitLab’s actual group structure rather than a separately maintained ownership model: move a project between GitLab groups, and its catalog ownership follows without any manual update.
How sign-in maps to catalog identity#
When you sign in with GitLab, an OAuth resolver matches your GitLab username against existing catalog User entities and signs you in as that entity — this is why a catalog User’s metadata.name is always the person’s GitLab handle, not a display name or email. There is no separate IDP identity to create: your GitLab account is your IDP account.
Why the GitLab integration token is dual-purpose#
The IDP’s GitLab integration uses a single personal access token with full api scope, not the narrower read_api. It needs write access because the same token drives two things: reading the group structure to populate the catalog, and creating projects and adding maintainers when someone runs the New SKA GitLab Project template. A read-only token would support the catalog but not the scaffolder.
Plugin architecture#
Beyond stock Backstage functionality (catalog, scaffolder, search, TechDocs), SKAO maintains its own plugins for capabilities specific to its infrastructure. Some are frontend-and-backend pairs — the Core Dumps Browser, which reads crash artefacts out of S3 rather than anything Backstage understands natively, ships as a frontend plugin plus a -be suffixed backend plugin, so the two can be deployed and scaled independently. Others are backend-only: the scaffolder actions and validation behind the New SKA GitLab Project template have no frontend package of their own — the template’s custom form fields are registered directly in the main application instead.
Permissions#
The IDP has Backstage’s permission framework enabled, but SKAO has not yet defined fine-grained policies — every signed-in user currently has the same access. Treat this as an interim state: expect finer-grained permissions (for example, restricting who can run certain scaffolder templates) as the platform matures.