Zum Inhalt springen
Trainingslager IT-Trainingslager

Tag 6: Templates für Fortgeschrittene

Ziel: Du baust ein Template mit Katalog-Feldern, Bedingungen, Schleifen und einer eigenen Action, testest es per Dry-Run und steuerst Tasks per API. · Dauer: ca. 150 min · Voraussetzung: Tag 5

Briefing

  • Der Template Editor (Tab unter Create) zeigt Formulare live und führt Templates als Dry-Run aus: Dateien und Log ohne Repo und Katalog-Eintrag.
  • Feld-Erweiterungen wie EntityPicker und OwnerPicker holen Werte aus dem Katalog. Steps kennen if: (Bedingung) und each: (Schleife).
  • Fehlt eine Action, schreibst du sie selbst: ein kleines Backend-Modul mit createTemplateAction.
  • Alles, was der Wizard kann, geht auch per API: scaffolder/v2/….
Wizard / API ──► Task
                  fetch:template ─► fetch:template:file (each) ─► fetch:plain (if)
                  ─► debug:log ─► kranich:ticket:create ─► publish:gitea ─► register
Template Editor ──► Dry-Run: dieselben Steps, publish und register übersprungen

Drill 1: Actions und Filter nachschlagen

Ausgangslage ist das Ende von Tag 5: Gitea-Provider und publish:gitea sind installiert, kranich/templates liefert das Template node-service (mit Parameter port aus der Challenge). Bevor du ein Template schreibst, prüfst du, welche Actions und Nunjucks-Filter es gibt:

source ~/backstage-lab/setup/env.sh
~/backstage-lab/setup/portal.sh start
bs scaffolder/v2/actions | jq -r '.[].id' | wc -l
bs scaffolder/v2/actions | jq -r '.[].id' | grep -E '^(fetch|debug|publish:gitea)'
bs scaffolder/v2/templating-extensions | jq -r '.filters | keys[]'

Erwartet:

✔ Backstage läuft: http://localhost:3000 (Backend http://localhost:7007)
      40
debug:log
debug:wait
fetch:plain
fetch:plain:file
fetch:template
fetch:template:file
publish:gitea
parseEntityRef
parseRepoUrl
pick
projectSlug

Dazu kommen die eingebauten Nunjucks-Filter wie dump, join oder lower. Die Eingaben einer Action stehen im JSON Schema:

bs scaffolder/v2/actions | jq -r '.[] | select(.id=="fetch:template:file")
  | .schema.input | "Pflicht: \(.required | join(" "))",
    "Alle:    \(.properties | keys | join(" "))"'

Erwartet:

Pflicht: url targetPath
Alle:    cookiecutterCompat lstripBlocks replace targetPath token trimBlocks url values

Im GUI siehst du dasselbe: Create → Tab Actions. Links steht die Liste mit Suchfeld, rechts nach einem Klick die Tabellen Input und Output. Der Tab Templating Extensions daneben listet die Filter mit Beispielen.

Fortschritt speichern? Kostenlos registrieren

Drill 2: Eine eigene Action als Backend-Modul

Kranich will zu jedem neuen Service ein Onboarding-Ticket. Ein Ticketsystem gibt es im Lab nicht. Die Action schreibt deshalb eine Datei TICKET.md ins Repo und gibt eine Ticketnummer aus. yarn new erzeugt das Gerüst und trägt es im Backend ein:

~/backstage-lab/setup/portal.sh stop
cd ~/backstage-lab/portal
yarn new --select scaffolder-backend-module --option moduleId=kranich
grep -n kranich packages/backend/src/index.ts

Erwartet (gekürzt):

  templating    plugins/scaffolder-backend-module-kranich ✔
  backend       adding @internal/backstage-plugin-scaffolder-backend-module-kranich ✔
  executing     yarn install ✔
  executing     yarn lint --fix ✔
🎉  Successfully created scaffolder-backend-module
74:backend.add(import('@internal/backstage-plugin-scaffolder-backend-module-kranich'));

Das Gerüst enthält eine Beispiel-Action acme:example. Ersetze sie durch die eigene Action:

cd plugins/scaffolder-backend-module-kranich/src
rm actions/example.ts actions/example.test.ts
cat > actions/ticket.ts <<'EOF'
import { resolveSafeChildPath } from '@backstage/backend-plugin-api';
import { createTemplateAction } from '@backstage/plugin-scaffolder-node';
import { promises as fs } from 'node:fs';
import { setTimeout as sleep } from 'node:timers/promises';

// kranich:ticket:create – simuliert ein Ticketsystem: schreibt TICKET.md
export function createTicketAction() {
  return createTemplateAction({
    id: 'kranich:ticket:create',
    description: 'Legt ein Onboarding-Ticket an (Lab: Datei TICKET.md)',
    supportsDryRun: true,
    schema: {
      input: {
        title: z => z.string({ description: 'Titel des Tickets' }),
        team: z => z.string({ description: 'Zuständiges Team (Entity-Ref)' }),
        token: z => z.string({ description: 'API-Token' }).optional(),
        delaySeconds: z =>
          z.number({ description: 'Simulierte Antwortzeit' }).default(0),
      },
      output: {
        ticketId: z => z.string({ description: 'Nummer des Tickets' }),
      },
    },
    async handler(ctx) {
      const { title, team, token, delaySeconds } = ctx.input;
      ctx.logger.info(`Ticketsystem: Token ${token ? 'gesetzt' : 'fehlt'}`);
      // nur Demo: der Scaffolder maskiert Secrets im Log
      if (token) ctx.logger.info(`Token zur Kontrolle: ${token}`);
      await sleep(delaySeconds * 1000, undefined, { signal: ctx.signal });

      const ticketId = ctx.isDryRun ? 'KRA-DRYRUN' : `KRA-${Date.now() % 100000}`;
      const file = resolveSafeChildPath(ctx.workspacePath, 'TICKET.md');
      await fs.writeFile(file, `# ${ticketId}: ${title}\n\nTeam: ${team}\n`);
      ctx.logger.info(`Ticket ${ticketId} für ${team} angelegt`);
      ctx.output('ticketId', ticketId);
    },
  });
}
EOF
cat > module.ts <<'EOF'
import { createBackendModule } from '@backstage/backend-plugin-api';
import { scaffolderActionsExtensionPoint } from '@backstage/plugin-scaffolder-node';
import { createTicketAction } from './actions/ticket';

export const scaffolderModule = createBackendModule({
  pluginId: 'scaffolder',
  moduleId: 'kranich',
  register({ registerInit }) {
    registerInit({
      deps: { scaffolderActions: scaffolderActionsExtensionPoint },
      async init({ scaffolderActions }) {
        scaffolderActions.addActions(createTicketAction());
      },
    });
  },
});
EOF

Die wichtigsten Stellen:

Stelle Bedeutung
schema.input Zod-Schemas, daraus entsteht das JSON Schema im Tab Actions
supportsDryRun ohne true überspringt ein Dry-Run die Action
ctx.signal wird beim Abbrechen des Tasks ausgelöst (Drill 8)
resolveSafeChildPath verhindert Pfade wie ../../etc außerhalb des Workspace

Ein Unit-Test liegt im Begleitcode. Er nutzt createMockActionContext und ein temporäres Verzeichnis:

C=~/backstage-lab/code/tag06/scaffolder-backend-module-kranich
cp $C/src/actions/ticket.test.ts actions/
cd .. && yarn test --watchAll=false && yarn lint
cd ~/backstage-lab/portal && yarn tsc && ~/backstage-lab/setup/portal.sh start
bs scaffolder/v2/actions | jq -c '.[] | select(.id|startswith("kranich"))
  | {id, required: .schema.input.required}'

Erwartet (gekürzt):

PASS src/actions/ticket.test.ts
  kranich:ticket:create
    ✓ schreibt TICKET.md und gibt die Ticketnummer aus (8 ms)
Tests:       1 passed, 1 total
✔ Backstage läuft: http://localhost:3000 (Backend http://localhost:7007)
{"id":"kranich:ticket:create","required":["title","team"]}
  1. Klicke in der Sidebar auf Create, dann auf den Tab Actions.
  2. Klicke in der Liste auf kranich:ticket:create.
  3. Erwartet: rechts Beschreibung, Input mit title *, team *, token, delaySeconds und darunter Output wie in der Abbildung.
Tab Actions mit der eigenen Action kranich:ticket:create

Fortschritt speichern? Kostenlos registrieren

Drill 3: Das Template kranich-service

Das neue Template nutzt alles auf einmal. Hol dir zuerst das Template-Repo und die fertigen Hilfsdateien aus dem Begleitcode:

mkdir -p ~/backstage-lab/tag06 && cd ~/backstage-lab/tag06
git clone -q http://lab-admin:[email protected]:3300/kranich/templates.git
cd templates
cp -R ~/backstage-lab/code/tag06/templates/kranich-service .
find kranich-service -type f | sort

Erwartet:

kranich-service/ci/ci.yaml
kranich-service/skeleton/README.md
kranich-service/skeleton/catalog-info.yaml
kranich-service/skeleton/src/index.js
kranich-service/template.yaml
kranich-service/vorlagen/config.json

Die Vorlage für die Umgebungen zeigt Nunjucks-Logik mit {% if %} und einem Inline-if:

cat kranich-service/vorlagen/config.json

Erwartet:

{
  "service": "${{ values.name }}",
  "umgebung": "${{ values.umgebung }}",
  "port": {% if values.umgebung == 'prod' %}80{% else %}8080{% endif %},
  "logLevel": "${{ 'warn' if values.umgebung == 'prod' else 'debug' }}"
}

ci/ci.yaml ist ein Forgejo-Actions-Workflow mit ${{ forgejo.ref_name }}. Den kopiert fetch:plain unverändert, fetch:template würde den Ausdruck ersetzen und den Workflow zerstören. Jetzt die Template-Definition. Sie liegt schon im Ordner, hier der vollständige Inhalt zum Nachvollziehen:

apiVersion: scaffolder.backstage.io/v1beta3
kind: Template
metadata:
  name: kranich-service
  title: Kranich-Service
  description: Node.js-Service mit System, Umgebungen und optionaler CI
  tags: [nodejs, kranich]
spec:
  owner: plattform
  type: service
  parameters:
    - title: Service
      required: [name, description, system, owner]
      properties:
        name:
          title: Name
          type: string
          description: Name der Component (z. B. lager-scanner)
          ui:field: EntityNamePicker
          ui:autofocus: true
        description:
          title: Beschreibung
          type: string
        system:
          title: System
          type: string
          description: Zu welchem System gehört der Service?
          ui:field: EntityPicker
          ui:options:
            catalogFilter:
              kind: System
            defaultKind: System
            allowArbitraryValues: false
        owner:
          title: Owner
          type: string
          ui:field: OwnerPicker
          ui:options:
            catalogFilter:
              kind: Group
              spec.type: team
    - title: Optionen
      properties:
        umgebungen:
          title: Umgebungen
          description: Je Umgebung entsteht eine Datei im Ordner config
          type: array
          items:
            type: string
            enum: [dev, test, prod]
          uniqueItems: true
          default: [dev]
          ui:widget: checkboxes
        ci:
          title: Forgejo-Actions-Workflow anlegen
          type: boolean
          default: false
        ticketToken:
          title: Token für das Ticketsystem
          type: string
          ui:field: Secret
    - title: Repository
      required: [repoUrl]
      properties:
        repoUrl:
          title: Ablageort
          type: string
          ui:field: RepoUrlPicker
          ui:options:
            allowedHosts: ['127.0.0.1:3300']
            allowedOwners: [kranich]
  steps:
    - id: fetch
      name: Skeleton füllen
      action: fetch:template
      input:
        url: ./skeleton
        values:
          name: ${{ parameters.name }}
          description: ${{ parameters.description }}
          owner: ${{ parameters.owner }}
          system: ${{ parameters.system }}
    - id: config
      name: Konfiguration je Umgebung
      each: ${{ parameters.umgebungen }}
      action: fetch:template:file
      input:
        url: ./vorlagen/config.json
        targetPath: config/${{ each.value }}.json
        values:
          name: ${{ parameters.name }}
          umgebung: ${{ each.value }}
    - id: ci
      name: CI-Workflow kopieren
      if: ${{ parameters.ci }}
      action: fetch:plain
      input:
        url: ./ci
        targetPath: .forgejo/workflows
    - id: log
      name: Eingaben prüfen
      action: debug:log
      input:
        message: >-
          Repo ${{ parameters.repoUrl | parseRepoUrl | pick('repo') }}
          für Team ${{ parameters.owner | parseEntityRef | pick('name') }}
        listWorkspace: true
    - id: ticket
      name: Onboarding-Ticket anlegen
      action: kranich:ticket:create
      input:
        title: Onboarding ${{ parameters.name }}
        team: ${{ parameters.owner }}
        token: ${{ secrets.ticketToken }}
        delaySeconds: 10
    - id: publish
      name: Repo in Forgejo anlegen
      action: publish:gitea
      input:
        repoUrl: ${{ parameters.repoUrl }}
        description: ${{ parameters.description }}
        defaultBranch: main
        gitCommitMessage: Erzeugt aus Template kranich-service
        gitAuthorName: Backstage Scaffolder
        gitAuthorEmail: [email protected]
    - id: register
      name: Im Katalog registrieren
      action: catalog:register
      input:
        repoContentsUrl: ${{ steps.publish.output.repoContentsUrl }}
        catalogInfoPath: catalog-info.yaml
  output:
    links:
      - title: Repository in Forgejo
        url: ${{ steps.publish.output.repoContentsUrl }}
      - title: Im Katalog öffnen
        icon: catalog
        entityRef: ${{ steps.register.output.entityRef }}
    text:
      - title: Nächste Schritte
        content: |
          **${{ parameters.name }}** ist angelegt.

          - Repo: `${{ parameters.repoUrl | projectSlug }}`
          - Umgebungen: ${{ parameters.umgebungen | join(', ') }}
          - CI-Workflow: ${{ 'ja' if parameters.ci else 'nein' }}
          - Ticket: ${{ steps.ticket.output.ticketId }}

Was neu ist gegenüber Tag 5:

Stelle Wirkung
EntityNamePicker prüft das Format eines Entity-Namens schon im Formular
EntityPicker + catalogFilter Auswahlliste aller Systems; liefert system:default/…
each: Step läuft je Listeneintrag einmal, der Wert steht in each.value
if: Step läuft nur, wenn der Ausdruck wahr ist, sonst „Skipping“
ui:field: Secret Wert landet in secrets.ticketToken, nicht in den Parametern
output.text Markdown-Kasten auf der Task-Seite

Ins Repo damit, plus eine Zeile in der Location-Datei:

echo '    - ./kranich-service/template.yaml' >> templates.yaml
git add -A
git -c user.name="Lab Admin" -c [email protected] \
  commit -qm "Template kranich-service" && git push -q origin main
bs catalog/refresh -X POST -H 'Content-Type: application/json' \
  -d '{"entityRef":"location:default/kranich-templates"}' -w '%{http_code}\n'
sleep 20
bs 'catalog/entities?filter=kind=template' | jq -r '.[].metadata.name'

Erwartet:

200
node-service
kranich-service

Tipp: EntityNamePicker prüft nur das Format, nicht, ob der Name im Katalog schon vergeben ist. Für so eine Prüfung brauchst du eine eigene Feld-Erweiterung im Frontend (Tag 11).

Fortschritt speichern? Kostenlos registrieren

Drill 4: Formular live bauen im Template Editor

  1. Klicke auf Create und dann auf den Tab Template Editor. Vier Karten erscheinen: Load Template Directory, Create New Template, Template Form Playground und Custom Field Explorer.
  2. Klicke auf Template Form Playground, dann oben auf TEMPLATES und wähle Kranich-Service.
  3. Links steht der parameters-Teil als YAML, rechts das fertige Formular. Trage bei Name lager-etiketten ein.
  4. Erwartet: die Ansicht wie in der Abbildung.
Template Form Playground mit dem Template Kranich-Service

Ändere links eine Zeile, etwa title: Name in title: Service-Name. Das Formular rechts übernimmt das sofort. So probierst du ui:options aus, ohne zu pushen. Gespeichert wird hier nichts.

Die drei Symbole rechts oben öffnen den Custom Fields Explorer, die Installed Actions Documentation und die Templating Extensions Documentation. PUBLISH zeigt nur eine Anleitung: Änderungen gehören per Pull Request ins Template-Repo.

Fortschritt speichern? Kostenlos registrieren

Drill 5: Dry-Run im Template Editor

Der Playground kennt nur das Formular. Für einen Probelauf mit Skeleton lädt der Editor das ganze Template-Verzeichnis aus deinem Dateisystem.

  1. Klicke im Tab Template Editor auf Load Template Directory.
  2. Wähle den Ordner ~/backstage-lab/tag06/templates/kranich-service und erlaube Chrome den Zugriff.
  3. Links erscheinen skeleton, ci, vorlagen und template.yaml, in der Mitte der Editor, rechts das Formular.
  4. Fülle das Formular aus: lager-etiketten, eine Beschreibung, System Sendungsverfolgung, Owner Team Sendung. Bei Optionen zusätzlich test und Forgejo-Actions-Workflow anlegen anhaken, ein beliebiges Token, bei Repository lager-etiketten.
  5. Klicke auf Review und Create.
  6. Erwartet: unten Dry-run results mit Result 1. Im Tab Files stehen .forgejo, config mit dev.json und test.json, src, README.md, TICKET.md und catalog-info.yaml wie in der Abbildung.
Template Editor mit Dry-Run-Ergebnis und TICKET.md der eigenen Action

Die Tabs Log und Output zeigen Task-Log und output.text. Das Download-Symbol packt alle Dateien als ZIP. Änderungen im Editor schreibt das Disketten-Symbol zurück in den Ordner.

Achtung: Load Template Directory braucht die File System Access API, also Chrome oder Edge mit localhost oder HTTPS. In Firefox und Safari ist die Karte ausgegraut. Außerdem zeigt der Editor Umlaute aus dem Skeleton in 1.55 verstümmelt an (für), weil er Dateien mit btoa überträgt. Der echte Lauf und der Dry-Run per API (Drill 6) sind davon nicht betroffen.

Fortschritt speichern? Kostenlos registrieren

Drill 6: Dry-Run per API

Derselbe Probelauf geht ohne Browser, etwa in einer Pipeline vor dem Merge ins Template-Repo. Der Endpunkt POST scaffolder/v2/dry-run will die Template-Definition als JSON, die Formularwerte und alle Dateien base64-kodiert. Das Skript im Begleitcode baut den Request zusammen:

sed -n 8,16p ~/backstage-lab/code/tag06/dryrun.sh

Erwartet:

files=$(cd "$dir" && find . -type f ! -path './.git/*' | sed 's|^\./||' | sort \
  | while read -r f; do
      jq -n --arg p "$f" --arg c "$(base64 < "$f" | tr -d '\n')" \
        '{path: $p, base64Content: $c}'
    done | jq -s .)
template=$(bs "catalog/entities/by-name/template/$ref")
jq -n --argjson t "$template" --argjson f "$files" --slurpfile v "$3" \
  '{template: $t, values: $v[0], directoryContents: $f}' \
  | bs scaffolder/v2/dry-run -X POST -H 'Content-Type: application/json' -d @-

Die Template-Definition kommt hier aus dem Katalog, die Dateien aus dem lokalen Ordner. Jetzt die Werte und der Lauf:

cd ~/backstage-lab/tag06
cat > werte.json <<'EOF'
{
  "name": "lager-scanner",
  "description": "Scanner-Ereignisse aus den Depots",
  "system": "system:default/sendungsverfolgung",
  "owner": "group:default/team-sendung",
  "umgebungen": ["dev", "prod"],
  "ci": true,
  "repoUrl": "127.0.0.1:3300?owner=kranich&repo=lager-scanner"
}
EOF
~/backstage-lab/code/tag06/dryrun.sh template:default/kranich-service \
  templates/kranich-service werte.json > dry.json
jq -r '.directoryContents[].path' dry.json
jq -r '.log[].body.message' dry.json | grep -E '^(Beginning|Skipping)'

Erwartet:

README.md
TICKET.md
catalog-info.yaml
src/index.js
config/dev.json
config/prod.json
.forgejo/workflows/ci.yaml
Beginning step Skeleton füllen
Beginning step Konfiguration je Umgebung
Beginning step CI-Workflow kopieren
Beginning step Eingaben prüfen
Beginning step Onboarding-Ticket anlegen
Beginning step Repo in Forgejo anlegen
Skipping because publish:gitea does not support dry-run
Beginning step Im Katalog registrieren
Skipping because catalog:register does not support dry-run

each und if haben gearbeitet, die Filter auch. Ein Blick ins Log und in eine erzeugte Datei:

jq -r '.log[].body.message' dry.json | sed 's/\x1b\[[0-9;]*m//g' \
  | grep -E '^info: (Repo|Running step each)'
jq -r '.directoryContents[] | select(.path=="config/prod.json")
  | .base64Content' dry.json | base64 -d
jq -r '.output.text[0].content' dry.json

Erwartet:

info: Running step each: {"key":"0","value":"dev"}
info: Running step each: {"key":"1","value":"prod"}
info: Repo lager-scanner für Team team-sendung
{
  "service": "lager-scanner",
  "umgebung": "prod",
  "port": 80,
  "logLevel": "warn"
}
**lager-scanner** ist angelegt.

- Repo: `kranich/lager-scanner`
- Umgebungen: dev, prod
- CI-Workflow: ja
- Ticket: KRA-DRYRUN

Die eigene Action läuft im Dry-Run mit, weil sie supportsDryRun: true setzt. ctx.isDryRun liefert ihr die Nummer KRA-DRYRUN statt einer echten.

Fortschritt speichern? Kostenlos registrieren

Drill 7: Tasks per Wizard und per API

Zuerst der echte Lauf im GUI:

  1. Klicke auf Create und bei Kranich-Service auf CHOOSE.
  2. Fülle den Schritt Service wie in Drill 5 aus (lager-etiketten). Die Liste bei System zeigt nur Systems: Sendungsverfolgung und examples.
  3. Klicke auf Next. Erwartet: Schritt Optionen wie in der Abbildung. Hake test und den Workflow an, trage ein Token ein. Es erscheint nur als Punkte.
Wizard-Schritt Optionen mit Checkboxen und Secret-Feld
  1. Klicke auf Next, trage bei Repository lager-etiketten ein, dann Review und Create.
  2. Erwartet: sieben grüne Steps, der Ticket-Step braucht rund 10 Sekunden. Darunter die Links und der Kasten Nächste Schritte wie in der Abbildung.
Task-Seite mit sieben Steps und dem Markdown-Kasten aus output.text

Was wurde aus dem Token? In den Parametern steht nur ein Platzhalter, im Log die Maske:

ID=$(bs 'scaffolder/v2/tasks?createdBy=user:default/thomas.zachmann' \
  | jq -r '.tasks[0].id')
bs scaffolder/v2/tasks/$ID | jq -c '.spec.parameters | {ticketToken, umgebungen}'
bs "scaffolder/v2/tasks/$ID/events" | jq -r '.[].body.message' | grep Token

Erwartet:

{"ticketToken":"*******************","umgebungen":["dev","test"]}
info: Ticketsystem: Token gesetzt
info: Token zur Kontrolle: ***

Jetzt dasselbe per API. POST scaffolder/v2/tasks will templateRef, values und optional secrets. Die Werte aus Drill 6 passen direkt:

cd ~/backstage-lab/tag06
jq -n --slurpfile v werte.json '{templateRef: "template:default/kranich-service",
  values: $v[0], secrets: {ticketToken: "lab-ticket-token-42"}}' > auftrag.json
ID=$(bs scaffolder/v2/tasks -X POST -H 'Content-Type: application/json' \
  -d @auftrag.json | jq -r .id); echo $ID
sleep 20
bs scaffolder/v2/tasks/$ID | jq '{status, createdBy}'
curl -sf -u "$ADMIN" "$FORGEJO/api/v1/repos/kranich/lager-scanner/raw/TICKET.md"

Erwartet:

e0ee0179-daf6-475f-9da6-1dd69abaa819
{
  "status": "completed",
  "createdBy": null
}
# KRA-23452: Onboarding lager-scanner

Team: group:default/team-sendung

createdBy ist leer: Das Lab-Token gehört zum Dienst lab-cli, nicht zu einem User. Prüfe die Liste:

  1. Klicke auf den Tab Tasks. Unter TASK OWNER ist Owned gewählt, du siehst nur deinen Lauf.
  2. Klicke auf All.
  3. Erwartet: alle Läufe wie in der Abbildung; die per API gestarteten haben den Owner Unknown.
Tab Tasks mit allen Läufen, API-Läufe ohne Owner

Dieselbe Liste per API, neueste zuerst:

bs 'scaffolder/v2/tasks?limit=3&order=desc:created_at' \
  | jq -r '.tasks[] | "\(.status)  \(.createdBy // "-")  \(.spec.parameters.name)"'

Erwartet:

completed  -  lager-scanner
completed  user:default/thomas.zachmann  lager-etiketten
completed  -  tour-api

Fortschritt speichern? Kostenlos registrieren

Drill 8: Einen Task abbrechen

Der Ticket-Step wartet 10 Sekunden. In diese Lücke schickst du den Abbruch:

cd ~/backstage-lab/tag06
jq '.values.name="lager-abbruch"
  | .values.repoUrl="127.0.0.1:3300?owner=kranich&repo=lager-abbruch"' \
  auftrag.json > abbruch.json
ID=$(bs scaffolder/v2/tasks -X POST -H 'Content-Type: application/json' \
  -d @abbruch.json | jq -r .id)
sleep 4; bs scaffolder/v2/tasks/$ID | jq -r .status
bs scaffolder/v2/tasks/$ID/cancel -X POST; echo
sleep 3; bs scaffolder/v2/tasks/$ID | jq -r .status

Erwartet:

processing
{"status":"cancelled"}
failed

Die Events zeigen, was passiert ist:

bs "scaffolder/v2/tasks/$ID/events" \
  | jq -r '.[] | (.body.message | split("\n")[0][0:50]) as $m
    | "\(.type) \(.body.stepId // "-") \($m)"' | sed 's/\x1b\[[0-9;]*m//g' | tail -5
curl -s -o /dev/null -w '%{http_code}\n' -u "$ADMIN" \
  "$FORGEJO/api/v1/repos/kranich/lager-abbruch"

Erwartet:

cancelled ticket Step ticket has been cancelled.
log ticket AbortError: The operation was aborted
log publish Skipping step publish because a previous step fail
log register Skipping step register because a previous step fai
completion - Run completed with status: failed
404

Warum klappt das so sauber? Der Abbruch löst ctx.signal aus, sleep bricht mit AbortError ab, und alle folgenden Steps fallen weg. Eine Action, die das Signal ignoriert, läuft bis zum Ende ihres Steps weiter. Der Gesamtstatus heißt danach failed, ein Event vom Typ cancelled markiert den Abbruch. Im GUI steht während des Laufs oben rechts auf der Task-Seite Cancel.

Fortschritt speichern? Kostenlos registrieren

Kontrollpunkt

cat > ~/backstage-lab/tag06/kontrollpunkt.sh <<'EOF'
#!/usr/bin/env bash
# kontrollpunkt.sh – Kontrollpunkt Tag 6 (✔/✘). Exit-Code = Anzahl Fehler.
source "${LAB:-$HOME/backstage-lab}/setup/env.sh"
fail=0
t() { if eval "$2" >/dev/null 2>&1; then echo "✔ $1"
  else echo "✘ $1"; fail=$((fail+1)); fi; }
R=$FORGEJO/api/v1/repos/kranich

t "Eigene Action kranich:ticket:create installiert" \
  "bs scaffolder/v2/actions | jq -e '.[] | select(.id==\"kranich:ticket:create\")'"
t "Filter parseRepoUrl verfügbar" \
  "bs scaffolder/v2/templating-extensions | jq -e '.filters.parseRepoUrl'"
t "Template kranich-service registriert" \
  "bs catalog/entities/by-name/template/default/kranich-service"
t "lager-scanner: config/prod.json (each) und CI-Workflow (if)" \
  "curl -sf -u \$ADMIN \$R/lager-scanner/contents/config/prod.json \
   && curl -sf -u \$ADMIN \$R/lager-scanner/contents/.forgejo/workflows/ci.yaml"
t "lager-scanner: TICKET.md aus der eigenen Action" \
  "curl -sf -u \$ADMIN \$R/lager-scanner/raw/TICKET.md | grep -q '^# KRA-'"
t "Component lager-scanner gehört zum System sendungsverfolgung" \
  "bs catalog/entities/by-name/component/default/lager-scanner \
     | jq -e '.spec.system==\"system:default/sendungsverfolgung\"'"
t "Abgebrochener Task hat kein Repo lager-abbruch erzeugt" \
  "! curl -sf -u \$ADMIN \$R/lager-abbruch"
exit "$fail"
EOF
bash ~/backstage-lab/tag06/kontrollpunkt.sh

Erwartet:

✔ Eigene Action kranich:ticket:create installiert
✔ Filter parseRepoUrl verfügbar
✔ Template kranich-service registriert
✔ lager-scanner: config/prod.json (each) und CI-Workflow (if)
✔ lager-scanner: TICKET.md aus der eigenen Action
✔ Component lager-scanner gehört zum System sendungsverfolgung
✔ Abgebrochener Task hat kein Repo lager-abbruch erzeugt

Challenge

Erweitere das Template node-service aus Tag 5 um eine Checkbox mit TechDocs (Standard: an). Ist sie gesetzt, bekommt das Repo mkdocs.yml, docs/index.md und die Annotation backstage.io/techdocs-ref: dir:.. Außerdem soll jeder Lauf ein Onboarding-Ticket anlegen und die Nummer auf der Task-Seite anzeigen. Lege damit paket-api für Team Web an.

Hinweis: Für die Annotation reicht ein {%- if values.techdocs %}-Block in skeleton/catalog-info.yaml; das Docs-Gerüst holt ein zweiter fetch:template-Step mit if:.

Lösung

In template.yaml kommt unter properties des Schritts Service (nach port) dazu:

        techdocs:
          title: mit TechDocs
          description: Legt mkdocs.yml und docs/index.md an
          type: boolean
          default: true

Unter values des Steps fetch die Zeile techdocs: ${{ parameters.techdocs }}, danach zwei neue Steps vor publish:

    - id: techdocs
      name: TechDocs-Gerüst
      if: ${{ parameters.techdocs }}
      action: fetch:template
      input:
        url: ./techdocs
        values:
          name: ${{ parameters.name }}
          description: ${{ parameters.description }}
    - id: ticket
      name: Onboarding-Ticket anlegen
      action: kranich:ticket:create
      input:
        title: Onboarding ${{ parameters.name }}
        team: ${{ parameters.owner }}

Und unter output:

    text:
      - title: Ticket
        content: Onboarding-Ticket **${{ steps.ticket.output.ticketId }}** ist angelegt.

Der Kopf von skeleton/catalog-info.yaml sieht dann so aus (das - in {%- entfernt den Zeilenumbruch davor):

metadata:
  name: ${{ values.name }}
  description: ${{ values.description | dump }}
  tags: [nodejs]
{%- if values.techdocs %}
  annotations:
    backstage.io/techdocs-ref: dir:.
{%- endif %}

Alle Dateien liegen im Begleitcode. Übernehmen, pushen, per API anlegen:

cd ~/backstage-lab/tag06/templates/node-service
L=~/backstage-lab/code/tag06/challenge/node-service
cp $L/template.yaml . && cp $L/skeleton/catalog-info.yaml skeleton/
cp -R $L/techdocs . && cd ..
git add -A && git -c user.name="Lab Admin" -c [email protected] \
  commit -qm "TechDocs-Option und Ticket" && git push -q origin main
bs catalog/refresh -X POST -H 'Content-Type: application/json' \
  -d '{"entityRef":"template:default/node-service"}' -w '%{http_code}\n'
ID=$(bs scaffolder/v2/tasks -X POST -H 'Content-Type: application/json' -d '{
  "templateRef": "template:default/node-service",
  "values": {"name": "paket-api", "description": "Paketdaten für Partner",
    "owner": "group:default/team-web", "port": 8082, "techdocs": true,
    "repoUrl": "127.0.0.1:3300?owner=kranich&repo=paket-api"}}' | jq -r .id)
sleep 15
curl -sf -u "$ADMIN" "$FORGEJO/api/v1/repos/kranich/paket-api/contents" \
  | jq -r '.[].path' | tr '\n' ' '; echo
bs "scaffolder/v2/tasks/$ID/events" \
  | jq -r '.[] | select(.type=="completion") | .body.output.text[0].content'

Erwartet:

200
README.md TICKET.md catalog-info.yaml docs mkdocs.yml package.json src
Onboarding-Ticket **KRA-18820** ist angelegt.

Mit "techdocs": false meldet das Log Skipping step techdocs because its if condition was false, und catalog-info.yaml hat keine annotations. Den TechDocs-Tab füllt erst Tag 7.

Fortschritt speichern? Kostenlos registrieren

Enterprise-Notiz

  • Eigene Actions sind Backend-Code mit den Rechten des Scaffolders. Sie gehören in Review und Tests wie jedes Plugin; Secrets kommen über secrets, nie über parameters, und nie ins Log.
  • Template-Repos bekommen eine Pipeline, die bei jedem Pull Request scaffolder/v2/dry-run aufruft. Ein kaputtes Template fällt so vor dem Merge auf, nicht beim ersten Nutzer.
  • Wer Templates ausführen, abbrechen oder per Dry-Run testen darf, steuern Permissions (scaffolder.task.create, scaffolder.task.cancel, scaffolder.template.dry-run, Tag 12).
  • Tasks per API mit einem Dienst-Token haben keinen Owner. In Produktion besser mit dem Token des auslösenden Users arbeiten oder den Aufrufer im Audit-Log zuordnen.
  • Echte Ticket- oder Freigabe-Actions müssen idempotent sein: Ein Task kann abbrechen oder mit Retry erneut laufen.