Skip to content

Backstage Platform Engineer Walkthrough

You're a platform engineer responsible for maintaining and evolving your organization's Internal Developer Platform (IDP) built on Backstage. You want to expose SkillMeat's artifact catalog (skills, commands, agents, workflows) to your developers as a self-service discovery and deployment capability within Backstage.

This walkthrough guides you from zero to a fully integrated Backstage instance where developers can browse, search, and deploy SkillMeat artifacts directly in your IDP. You'll install the plugin, configure catalog integration, surface the artifact browser in your developer portal, and set up governance policies.

Prerequisites

Before you start, ensure you have:

What you need

  • Backstage v1.27.x or later — compatibility tested; RHDH 1.3+ also supported
  • SkillMeat API v1.0.0+ deployed and network-reachable from your Backstage instance
  • Admin or platform engineer access to your Backstage app configuration
  • Node.js 18+ for plugin build/installation
  • SkillMeat API credentials — bearer token or service account (you'll configure this in Step 1)
  • Access to Backstage app-config.yaml for plugin configuration
  • Familiarity with Backstage architecture — entity providers, scaffolder templates, RBAC basics

Step 1: Install the SkillMeat Plugin

You'll install the SkillMeat frontend and scaffolder backend plugins into your Backstage instance. This step handles plugin package installation, configuration, and initial verification.

Duration: 15–20 minutes

Follow the detailed installation guide:

→ Backstage Plugin Installation & Configuration

This guide covers: - Installing the frontend plugin (@skillmeat/backstage-plugin) - Installing the scaffolder backend plugin (@skillmeat/backstage-plugin-scaffolder-backend) - Configuring app-config.yaml with SkillMeat API endpoint and authentication - Health check and plugin load verification

Verification Checkpoint 1: Plugin Loads

After installation, verify the plugin loads correctly:

  1. Rebuild your Backstage app: yarn tsc && yarn build
  2. Start the dev or production server
  3. Check the browser console for any plugin errors (should see no @skillmeat errors)
  4. Navigate to any entity page — you should see SkillMeat plugin UI elements or tabs appearing

Expected outcome: Plugin loads without errors; no red X or missing UI elements.

Step 2: Configure Artifact Catalog Integration

Now you'll set up catalog integration so Backstage can discover and sync SkillMeat artifacts into Backstage's entity catalog. This enables developers to search and filter artifacts alongside their other catalog entities.

Duration: 20–30 minutes

Follow the detailed catalog integration guide:

→ Backstage Catalog Integration Guide

This guide covers: - Entity provider overview (how Backstage discovers SkillMeat artifacts) - Configuration in app-config.yaml (entity provider URL, refresh intervals) - Entity schema mapping (how SkillMeat artifact metadata maps to Backstage entities) - Manual and automatic refresh triggers - Troubleshooting sync failures

Verification Checkpoint 2: Artifacts Appear in Catalog

After configuration, verify that artifacts sync into your Backstage catalog:

  1. Open the Backstage Catalog page
  2. Look for a new entity category or filter for "SkillMeat Artifacts" or "Skills"
  3. Search for a known artifact (e.g., "canvas" if using Anthropic's example skills)
  4. Verify the artifact entity shows:
  5. Correct name and description
  6. Artifact type and version
  7. Ownership/maintainer info

Expected outcome: At least 2–3 SkillMeat artifacts appear in your catalog and are searchable.

Step 3: Expose Artifact Browser to Developers

With artifacts now in your catalog, you'll surface the artifact browser UI in your developer portal so developers can discover, view details, and deploy artifacts without leaving Backstage.

Duration: 15–25 minutes

Follow the detailed developer portal integration guide:

→ Backstage Developer Portal Integration

This guide covers: - Artifact browser UI component (visual layout, search, filters) - Integration with Backstage entity pages (viewing artifact details, dependencies) - Developer workflow (browsing → viewing details → deploying via templates) - Dashboard or portal surface placement (where developers see artifacts) - Optional: CI/CD integration (showing deployment status in Backstage)

Verification Checkpoint 3: Developers Can Browse Artifacts

After portal integration, verify developers can discover and interact with artifacts:

  1. Give a test developer account access to your Backstage instance
  2. Have them navigate to the artifact browser or search interface
  3. Test search (e.g., search for "skill" or "canvas")
  4. Have them click an artifact to view details
  5. Verify they can see artifact metadata, version, and usage examples

Expected outcome: Non-admin developers can browse, search, and view artifact details in Backstage without CLI access.

Step 4: Set Up Governance and Permissions

Finally, you'll define organizational policies for artifact adoption, enforce version constraints, and audit artifact deployments. This ensures artifact usage aligns with your organization's standards and compliance requirements.

Duration: 20–30 minutes

Follow the detailed governance and permissions guide:

→ Backstage Governance & Permissions Guide

This guide covers: - Backstage permission model and RBAC (roles and groups) - Mapping Backstage groups to SkillMeat scopes (user, team, org) - Policy examples (version pinning, allowlist enforcement, audit logging) - Permission checks on deployment endpoints - Audit logging configuration

Verification Checkpoint 4: Policies Enforce Correctly

After setting up governance, verify that policies are enforced:

  1. Define a test policy (e.g., "only version v1.0.0+ of artifact X is approved")
  2. Have a test developer attempt to deploy a policy-violating artifact (e.g., v0.9.0)
  3. Verify they receive a permission denied or policy violation error
  4. Have them deploy a compliant artifact and verify success
  5. Check audit logs to confirm the deployment attempt is logged

Expected outcome: Policies block non-compliant deployments; compliant deployments succeed; audit trail records both attempts.

Summary: What You've Accomplished

By completing this walkthrough, you have:

  1. ✅ Installed SkillMeat plugins in Backstage (frontend + scaffolder backend)
  2. ✅ Integrated SkillMeat artifacts into your Backstage catalog (auto-synced, discoverable)
  3. ✅ Surfaced artifact browser to developers (self-service discovery and details in portal)
  4. ✅ Defined governance policies (version enforcement, compliance, audit trails)

Your Backstage instance now serves as a unified discovery and deployment hub for SkillMeat artifacts, enabling developers to adopt skills, commands, and workflows as part of their normal IDP workflow.

Next Steps

For Team / Enterprise Setup

If you're also managing team collections and artifact ownership, see the broader team and enterprise administration context:

→ Team / Enterprise Admin Walkthrough — covers team collection setup, marketplace publishing, and centralized governance beyond Backstage

For Advanced Integration

For programmatic integration patterns (CI/CD automation, agent runtimes, third-party apps consuming SkillMeat artifacts):

→ Programmatic API Usage Guide — (Phase 5) webhook subscriptions, version management via API, artifact download and distribution patterns

Troubleshooting

If you encounter issues during any step:

Getting Help

  • Review the Backstage Integration Overview for architecture and high-level concepts
  • Consult your Backstage documentation for entity provider and permission configuration specifics
  • Check the SkillMeat plugin README files in the GitHub repository for API-level details

Time to complete: ~60–90 minutes (all 4 steps)
Complexity: Intermediate (requires Backstage and IDP familiarity)
Prerequisites met: ✅