Lab: request a MicroBank change through an IDP

Read the integration in three parts

The catalog tells a learner what exists and who supports it. The template converts a constrained input into a draft PR. The existing GitOps process selects and applies a reviewed revision. Keeping those parts visible makes a failed request easier to diagnose.

In the template below, fetch:template renders a fixed skeleton, then publish:github:pull-request proposes the generated file. sourcePath selects the generated directory. The nested skeleton path reproduces the environment lab's existing local patch path. The backend action must actually be installed; a YAML step name cannot install its implementation.

The first patch changes a Deployment annotation outside the Pod template. It should leave the image and running application specification alone. That is a deliberately small integration test before the later artifact-release extension. Do not describe the annotation run as an autonomous full software delivery lifecycle.

Start with the working delivery path

Complete the local overlay, GitOps, and offline policy labs. Keep the platform Application under one owner. Choose Backstage or Port using the evaluation bite. The concrete example below uses a local Backstage development instance and GitHub PR creation; the Port alternative uses the same acceptance contract. Record either installation as unverified until you run it and retain the results.

The first request changes a harmless Ledger Deployment annotation. It proves the request-to-review-to-reconciliation connection. A full artifact release is the second exercise, after the small connection works. Record the annotation-only run as an integration check; it does not verify a complete automated release.

1. Prepare the portal separately

Follow Backstage's current standalone installation instructions, choosing supported Node/package-manager versions and recording the generated application version and lockfile. Keep its development backend private. Measure host memory and stop optional telemetry before running it alongside MicroBank.

Configure a GitHub integration limited to your practice repository. Follow the selected backend's authentication and permission guidance before enabling credential-backed actions for other users. The local demo authentication is not a shared production access model. Credentials belong in the private backend environment/configuration, never in the template below.

Install/register the supported GitHub scaffolder backend module following the official built-in-actions guide if absent. Confirm fetch:template and publish:github:pull-request are visible in the instance's /create/actions page. Install any missing action before proceeding.

2. Register actual services

Save platform/catalog/catalog-info.yaml in the practice repository. These are local lab entities. Replace the role with an actual owner model before wider use; the example role does not represent an existing team.

apiVersion: backstage.io/v1alpha1
kind: Group
metadata:
  name: microbank-maintainers
spec:
  type: team
  children: []
---
apiVersion: backstage.io/v1alpha1
kind: System
metadata:
  name: microbank
  description: Local banking application learning system
spec:
  owner: group:default/microbank-maintainers
---
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: microbank-accounts
  description: Transaction request API in the selected local profile
spec:
  type: service
  lifecycle: experimental
  owner: group:default/microbank-maintainers
  system: microbank
---
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: microbank-ledger
  description: Ledger consumer and balance API in the selected local profile
spec:
  type: service
  lifecycle: experimental
  owner: group:default/microbank-maintainers
  system: microbank

Register the reachable file URL using the catalog's existing-component flow. Verify the two Components resolve their owner and System. Add real source and runbook links. Register a worker or frontend only if your chosen application profile actually includes it.

3. Define a constrained request template

Create platform/templates/local-request/template.yaml. Replace the fixed repository and target-branch placeholders with your own practice repository and existing branch. Keep them fixed in the template rather than accepting a free-form destination from a user.

apiVersion: scaffolder.backstage.io/v1beta3
kind: Template
metadata:
  name: microbank-local-request
  title: Request a local MicroBank configuration change
  description: Open a reviewable annotation change; no direct deployment
spec:
  owner: group:default/microbank-maintainers
  type: service
  parameters:
    - title: Local change request
      required: [requestId]
      properties:
        requestId:
          title: Unique request ID
          type: string
          minLength: 3
          maxLength: 40
          pattern: '^[a-z0-9]+(-[a-z0-9]+)*
#x27;
  steps:
    - id: render
      name: Render the supported local patch
      action: fetch:template
      input:
        url: ./skeleton
        targetPath: request
        values:
          requestId: ${{ parameters.requestId }}
    - id: propose
      name: Open a draft pull request
      action: publish:github:pull-request
      input:
        repoUrl: github.com?owner=REPLACE_OWNER&repo=REPLACE_REPOSITORY
        targetBranchName: REPLACE_WITH_EXISTING_BRANCH
        branchName: requests/microbank-${{ parameters.requestId }}
        title: 'MicroBank local request: ${{ parameters.requestId }}'
        description: 'Review the local annotation patch and required checks before merging.'
        sourcePath: request
        draft: true
        update: false
  output:
    links:
      - title: Review the requested change
        url: ${{ steps.propose.output.remoteUrl }}

Save the following skeleton at platform/templates/local-request/skeleton/platform/workloads/overlays/local/request.yaml. Its relative path deliberately matches the existing environment lab patch:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: ledger
  annotations:
    platform.learnwithsk.dev/environment: local
    platform.learnwithsk.dev/request: ${{ values.requestId }}

Register the reachable template. Use Backstage's template editor/dry-run facility to inspect generated files before enabling publication. Confirm there is exactly one changed path, no Secret values, and no image or target changes. Verify the available action schema matches the inputs above for your installed version.

4. Follow one real request

Submit a unique ID such as local-review-001. The external effect is a draft PR in your own repository, not a deployment. Review the file diff, run manifest rendering and the owner policy checks, and retain their results tied to the PR revision. Transition the draft and merge through your actual review rules when ready.

The Application from the GitOps lab is pinned to a commit. Merging a PR therefore does not automatically deploy it. Update its targetRevision to the reviewed merged commit, inspect the diff, and request the same manual sync. Observe the Deployment annotation and confirm unchanged images and the saved transaction case.

Link the request, PR, checks, intended revision, observed sync result, and application evidence. Status integrations may initially be links; do not show live status that no backend integration collects.

5. Prove failure handling and a release extension

Test an invalid request ID in the form and a repeated valid ID. update: false is chosen to avoid silently rewriting an existing branch; inspect the installed action's collision result and document the retry procedure. Test a failed downstream policy check using a reviewed invalid patch on a separate practice branch. A failed check must not be reported as a successful deployment.

After the annotation path works, extend the request to a selected image from a trusted release inventory. Verify that the image was built/tested, constrain its repository/digest, update only the intended overlay, and preserve the same review, policy, reconciliation, and local verification chain. This requires an implemented release-selection action; accepting arbitrary text in a new field is not sufficient.

For Port, model the same service/owner relationships and constrained request, use its supported action execution backend to create the PR, and return the execution result. Compare permissions, inputs, duplicate-request behavior, and evidence to verify that the Port workflow provides the same behavior. This guide does not claim the Backstage YAML can be imported into Port.

Acceptance and cleanup

Record separately: catalog registered, template previewed, PR created, checks passed, reviewed commit synced, application verified, and failure recovered. Compare the observed task with the initial manual baseline. Mark unimplemented status integrations or artifact selection as pending.

Close unused practice PRs/branches through their normal lifecycle, stop the local portal when finished, and revoke temporary integration access if retiring it. Keep the canonical workload configuration and recovery records. Document the work publicly only with sanitized examples, while keeping the portal and deployment actions private.

Follow a request without a single success badge

Record the request ID, generated diff, PR, checked revision, reviewed merge, selected Application revision, sync result and application check separately. If the PR exists but a response was lost, find it before retrying. If it merged but the Application still points at the earlier commit, selecting the reviewed revision is the missing step.

A complete first run demonstrates catalog navigation and a constrained request through review and local reconciliation. A subsequent image release needs an implemented trusted release selector and its own tests. Keep those outcomes separate when you publish your learning notes.

Sources

Backstage setup↗, Catalog descriptors↗, Scaffolder actions↗, Template syntax↗, PR action schema↗, Template dry run↗, GitHub integration↗, Port actions↗.