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
EntityPickerundOwnerPickerholen Werte aus dem Katalog. Steps kennenif:(Bedingung) undeach:(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.tsErwartet (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());
},
});
},
});
EOFDie 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"]}
- Klicke in der Sidebar auf Create, dann auf den Tab Actions.
- Klicke in der Liste auf kranich:ticket:create.
- Erwartet: rechts Beschreibung, Input mit
title *,team *,token,delaySecondsund darunter Output wie in der Abbildung.
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 | sortErwartet:
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.jsonErwartet:
{
"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:
EntityNamePickerprü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
- 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.
- Klicke auf Template Form Playground, dann oben auf TEMPLATES und wähle Kranich-Service.
- Links steht der
parameters-Teil als YAML, rechts das fertige Formular. Trage bei Namelager-etikettenein. - Erwartet: die Ansicht wie in der Abbildung.
Ä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.
- Klicke im Tab Template Editor auf Load Template Directory.
- Wähle den Ordner
~/backstage-lab/tag06/templates/kranich-serviceund erlaube Chrome den Zugriff. - Links erscheinen
skeleton,ci,vorlagenundtemplate.yaml, in der Mitte der Editor, rechts das Formular. - 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 Repositorylager-etiketten. - Klicke auf Review und Create.
- Erwartet: unten Dry-run results mit Result
1. Im Tab Files stehen
.forgejo,configmitdev.jsonundtest.json,src,README.md,TICKET.mdundcatalog-info.yamlwie in der Abbildung.
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
localhostoder 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 mitbtoaü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.shErwartet:
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.jsonErwartet:
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:
- Klicke auf Create und bei Kranich-Service auf CHOOSE.
- Fülle den Schritt Service wie in Drill 5 aus
(
lager-etiketten). Die Liste bei System zeigt nur Systems: Sendungsverfolgung undexamples. - 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.
- Klicke auf Next, trage bei
Repository
lager-etikettenein, dann Review und Create. - 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.
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 TokenErwartet:
{"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:
- Klicke auf den Tab Tasks. Unter TASK OWNER ist Owned gewählt, du siehst nur deinen Lauf.
- Klicke auf All.
- Erwartet: alle Läufe wie in der Abbildung; die per API gestarteten haben den Owner Unknown.
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 .statusErwartet:
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.shErwartet:
✔ 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: trueUnter 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 überparameters, und nie ins Log. - Template-Repos bekommen eine Pipeline, die bei jedem Pull Request
scaffolder/v2/dry-runaufruft. 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.