Udvikling af de centrale pipelines

Denne vejledning er til udviklere, der vedligeholder det centrale ecreo-ci-cd-repository. Den dækker runneren, nye grupper, fælles hjælpere, tests og publicering. Tilpasninger, som kun gælder ét projekt, hører normalt til i projektets devops/steps/. Se Projektspecifikke scripts.

Repositoryets struktur

ecreo-ci-cd/
  src/
    scripts/
      setup/
      validate/
      validate-frontend/
      validate-dotnet/
      validate-umbraco-cloud-setup/
      validate-azure-web-app-setup/
      sync/
      build-frontend/
      deploy-umbraco-cloud/
      deploy-azure-web-app/
      update-dependencies/
    setup/
      run.sh
      bitbucket-pipelines.umbraco-cloud.yml
      bitbucket-pipelines.azure-web-apps.yml
      devops.env.example
  tests/
  docs-site/
    src/content/docs/
    astro.config.mjs
    package.json
  bitbucket-pipelines.yml
  AGENTS.md

src/scripts/ indeholder grupperne, som publiceres som zip-filer. src/setup/ indeholder runneren og de filer, projekterne bruger til installation. Repositoryets egen bitbucket-pipelines.yml publicerer løsningen til Azure Blob Storage.

Læs AGENTS.md før ændringer. Den indeholder aktuelle konventioner, testkommandoer og kendte begrænsninger.

Sådan afvikler runneren en gruppe

Grupperne kører i rækkefølgen fra --include. For hver gruppe gør run.sh følgende:

1. Henter <gruppe>.zip fra den fælles blob-container.
2. Pakker den ud i /tmp/devops-steps/<gruppe>/, hvis download lykkes.
3. Kopierer projektets lokale .sh-scripts fra devops/steps/<gruppe>/ ind over de centrale filer. Lokale filer med samme navn erstatter den centrale fil.
4. Kopierer lokale støttefiler med endelserne .bash og .json, når der er lokale .sh-scripts i gruppen.
5. Finder .sh-filer direkte i gruppemappen og sorterer dem efter filnavn.
6. Starter hvert script med Bash og sender argumenterne efter runnerens separate -- videre til det.

Et script, der returnerer en fejlkode, stopper kørslen. Hjælpefiler med .bash, .js og .json bliver ikke automatisk ekstra pipeline-trin.

Central download	Lokale scripts	Resultat
HTTP 200	Ingen	Kør de centrale scripts
HTTP 200	Findes	Flet filerne. Lokale navnesammenfald vinder
HTTP 404	Findes	Kør kun de lokale scripts
HTTP 404	Ingen	Fejl, fordi gruppen ender med nul scripts
HTTP 000 eller tom status	Findes	Den aktuelle runner forsøger også lokal fallback ved disse downloadfejl
Anden HTTP-status	Uanset lokale filer	Stop med fejl

En gruppe uden .sh-scripts fejler altid efter sammenfletningen. Der er ikke et generelt --dry-run-flag i runneren.

Tilføj en central gruppe

1. Opret src/scripts/<gruppenavn>/.
2. Tilføj scripts med trecifrede præfikser. Brug normalt 100_, 200_, 300_ og så videre.
3. Indlæs den fælles output-hjælper i hvert script.
4. Afprøv adfærden og kør de relevante tests før merge.
5. Merge til main, når ændringen er klar til publicering.
6. Lad projekterne tilføje gruppen til deres --include-liste, hvor den skal bruges.

Runneren kræver ingen registrering af nye grupper. Nummereringen efterlader plads til projekthooks før og efter de centrale scripts.

Eksempel på et script, som afhænger af tidligere trin:

#!/bin/bash
. "${CI_OUTPUT_LIB:-$(dirname "$0")/../lib/output.sh}"

if [[ -z "${MY_REQUIRED_VAR:-}" ]]; then
  dim "MY_REQUIRED_VAR mangler. Trinnet springes over."
  exit 0
fi

info "Kører det centrale trin."
# Udfør opgaven og kontrollér kommandoernes exitkoder.
echo "MY_RESULT=done" >> devops/temp/artifact.env
success "Trinnet er gennemført."

Eksemplet forudsætter, at værdien er tilgængelig i scriptets miljø. Læs tilstand fra artifact.env, hvis en tidligere proces har skrevet den dér. Et manglende input, som betyder, at der intet er at gøre, kan give exit 0. Manglende obligatorisk konfiguration skal derimod fejle med en tydelig besked og exit 1.

Delt tilstand i artifact.env

setup/100_set-variables.sh opretter devops/temp/artifact.env ud fra projektets devops/.env, fjerner kommentarer og tomme linjer og tilføjer de opløste værdier. Projektets .env skal have gyldig Bash-syntaks.

Efterfølgende scripts skriver til den fælles fil:

echo "MY_RESULT=done" >> devops/temp/artifact.env

Mange eksisterende scripts indlæser værdier med:

export $(cat devops/temp/artifact.env | xargs)

Vær opmærksom på begrænsninger ved mellemrum og quoting. Dependency-scripts bruger update-dependencies/artifact-env.bash til at læse filen som bogstavelige KEY=VALUE-data, fjerne matchende omgivende anførselstegn og håndtere CRLF.

Den genererede artifact.env må ikke indlæses som Bash med source eller .. Setup kan skrive uquoted værdier med $ fra Azure-brugernavne og passwords. Shell-substitution skal forblive bogstavelige data.

Fælles output og hjælpefiler

Runneren genererer output.sh ved opstart og sætter CI_OUTPUT_LIB til /tmp/devops-steps/lib/output.sh. Den aktuelle checkout har ikke en separat committed src/scripts/lib/output.sh; output-hjælperen ligger som heredoc i run.sh.

Brug de fælles funktioner, så terminaloutput og detaljerede logfiler er ens på tværs af grupper:

Funktion	Formål
info, dim, key_value	Information, forventede overspring og navngivne værdier
success, warn, error	Resultater, advarsler og fejl. error skal følges af en fejlkode, når trinnet skal stoppe
verbose, verbose_block	Detaljer kun i scriptets logfil, når CI_LOG_FILE er sat
wait_on_429	Retry-hjælp ved rate limiting fra Umbraco Cloud API

verbose-funktionerne skriver uden ANSI-farvekoder og gør intet, når CI_LOG_FILE ikke er sat. Log aldrig tokens, API-nøgler eller passwords, heller ikke som verbose-output.

wait_on_429 læser ventetiden fra API-beskedens “Try again in N seconds”, med en standard på 30 sekunder, og tilføjer to sekunders margen. Den returnerer 0, når kaldet kan forsøges igen, og 1, når budgettet er opbrugt. Standardbudgettet er 10 retries. Nulstil retry429=0 efter et vellykket API-kald, så kun sammenhængende 429-svar tæller.

Disse hjælpefiler har kopier, som skal holdes identiske:

Fil	Kopi i src/setup/run.sh
src/scripts/build-frontend/build-state.bash	BUILD_STATE_EOF-heredoc
src/scripts/update-dependencies/automation-reviewers.bash	REVIEWERS_EOF-heredoc

Hvis en separat output.sh bruges som redigeringskilde, skal dens indhold også svare til runnerens heredoc. Publiceringsjobbet opdaterer ikke automatisk disse kopier.

Oversigt over de centrale scripts

Gruppe	Scripts og opgave
setup	100_set-variables.sh indlæser argumenter og projektstandarder og opretter delt tilstand
validate	100_run-tests.sh kører frontend-validering og derefter .NET-validering via de medfølgende .bash-implementeringer
validate-frontend	100_run-tests.sh bruger frontend.bash til npm-tests eller fallback-build
validate-dotnet	100_run-tests.sh bruger dotnet.bash til Release-validering af solutionen
validate-umbraco-cloud-setup	100_check-required-variables.sh kontrollerer Cloud-variabler
validate-azure-web-app-setup	100_check-required-variables.sh kontrollerer Azure-variabler og Kudu URL
sync	100_get_latest_deployment.sh, 200_get_changes_by_id.sh og 300_apply_patch.sh henter ændringer, anvender patchen og håndterer commit og push
build-frontend	100_build-frontend-files.sh bygger frontend eller genbruger et aktuelt build
deploy-umbraco-cloud	100_prepare-upload-artifact.sh, 200_upload_artifact.sh, 300_start_deployment.sh og 400_get_deployment_status.sh pakker, uploader, starter og følger deployment
deploy-azure-web-app	100_publish-project.sh, 200_create-zip-package.sh, 300_test-kudu-auth.sh, 400_upload-zip.sh og 500_verify-deployment.sh publicerer, pakker og deployer via Kudu
update-dependencies	100_preflight.sh, 200_update-nuget.sh, 300_update-npm.sh, 400_enforce-policy.sh, 500_update-cdn.sh og 600_create-pr.sh samler dependency-opdateringer i en PR

Tilstand mellem de centrale trin

Værdi i artifact.env	Skrevet af	Brug
latestDeploymentId	sync/100_get_latest_deployment.sh	ID for seneste Cloud-deployment
remoteChanges	sync/200_get_changes_by_id.sh	Den hentede diff til patch-trinnet
updatedSha	sync/300_apply_patch.sh	HEAD efter synkroniseringen
ARTIFACT_FILE	deploy-umbraco-cloud/100_prepare-upload-artifact.sh	Sti til sources.zip
artifactId	deploy-umbraco-cloud/200_upload_artifact.sh	Det uploadede Cloud-artifact
deploymentId	deploy-umbraco-cloud/300_start_deployment.sh	Cloud-deployment, som status-trinnet følger
PUBLISH_OUTPUT	deploy-azure-web-app/100_publish-project.sh	Mappen med .NET publish-output
DEPLOY_ZIP	deploy-azure-web-app/200_create-zip-package.sh	Sti til Azure zipdeploy-pakken

Ved Cloud-deployment kopieres cloud.gitignore over .gitignore, og cloud.zipignore styrer udeladelser i upload-arkivet. Status-trinnet poller normalt hvert 25. sekund, mens deployment afventer eller er i gang. Et vellykket Cloud-deployment opretter et tag med formen deploy/<miljø>/<buildnummer>.

Build-genbrug gælder kun inden for samme runner-kørsel. Frontend-build gør et tidligere .NET-build ugyldigt. Ændrer et hook ignorerede kompileringsinput, skal det kalde invalidate_dotnet_build via CI_BUILD_STATE_LIB eller fjerne devops/temp/build-state. Se Grupper og buildforløb.

Logs og artifacts

Runneren sætter CI_LOG_FILE til /tmp/devops-output/logs/<gruppe>__<script>.log og CI_OUTPUT_DIR til /tmp/devops-output. Skriv ZIP-filer til CI_OUTPUT_DIR, så de ikke havner i arbejdstræet midt i kørslen.

Hvert scripts stdout og stderr opsamles med tee. verbose-funktionerne tilføjer ekstra detaljer til samme logfil. En exit-trap kopierer output til devops/output/, også ved fejl, når trappen er installeret.

Kopien af artifact.env filtrerer linjer med API_KEY og PASSWORD fra. Filtreringen dækker ikke alle mulige hemmeligheder. Skriv derfor ikke andre følsomme værdier til output.

Et Bitbucket-step skal have devops/output/** i sin artifact-deklaration, hvis filerne skal kunne hentes efter kørslen. Det gælder ikke alle maintenance-steps i de aktuelle templates. Se Logs og fejlfinding.

Tests før commit

Kør fra repositoryets rod i Bash, eksempelvis Git Bash eller WSL på Windows. Suitefilerne er shell- og Node-tests, som afprøver scripts og runneradfærd.

bash tests/test-group-resolution.sh
bash tests/test-args-passthrough.sh
bash tests/test-dry-run.sh
bash tests/test-sync-patch-fallback.sh
bash tests/test-sync-ignored-files.sh
bash tests/test-dependency-pr-description.sh
bash tests/test-dependency-artifact-env.sh
bash tests/test-dependency-existing-pr-update.sh
bash tests/test-pipeline-update-commit-message.sh
bash tests/test-npm-validation-fallback.sh
bash tests/test-build-reuse.sh
bash tests/test-scheduled-maintenance-pipeline.sh
bash tests/test-automation-reviewers.sh
bash tests/test-publish-tag.sh
node tests/test-cdn-updates.js
node tests/test-deployment-branches.js

Der er en kendt baseline-fejl i test-group-resolution.sh og test-dry-run.sh. Assertions for manglende --include og ukendte flags forventer teksten ERROR, mens output-hjælperen skriver ✗. De fejler også på den uændrede runner. Sammenlign med baseline, og adskil dem fra nye fejl.

Navnet test-dry-run.sh betyder ikke, at runneren har et --dry-run-flag. Ved ændringer i adfærd skal relevante regressionstests afprøve resultatet, herunder fejl og fallback, hvor det er relevant.

Publicering fra main

Push til main starter repositoryets publiceringspipeline:

1. Pak hver gruppes filer som <gruppe>.zip, og upload med overskrivning. For validate.zip tilføjes også frontend.bash og dotnet.bash fra de separate valideringsgrupper.
2. Upload run.sh.
3. Upload begge pipeline-templates.
4. Upload devops.env.example.
5. Upload dependency-updates.schema.json fra dependency-gruppen.
6. Tag den publicerede BITBUCKET_COMMIT som deploy/ci-scripts/<BITBUCKET_BUILD_NUMBER>, og push kun dette tag med pipeline-jobbets checkout-credentials.

Uploadfejl stopper jobbet før tagget. Tagget gør publiceringen sporbar i Git. Blobs overskrives fortsat på deres faste navne, og projekterne har ingen indbygget pinning af runner eller grupper.

Alle publicerede filer ligger under https://ecreociscripts.blob.core.windows.net/ci-scripts/. Der publiceres ikke en selvstændig zip til output-hjælperen, som genereres af runneren.

Variabler til publiceringsjobbet

Opret følgende under repositoryets Repository settings > Pipelines > Repository variables:

Variabel	Værdi	Sikret
AZURE_STORAGE_CONNECTION_STRING	Connection string til storage-kontoen ecreociscripts	Ja
AZURE_CONTAINER	ci-scripts	Nej

Connection string findes i Azure Portal under storage-kontoens Access keys. Den kan også hentes med Azure CLI, hvis du har den nødvendige adgang:

az storage account show-connection-string \
  --name ecreociscripts \
  --resource-group rg-ecreo-ci \
  --query connectionString \
  --output tsv

Kommandoen udskriver en hemmelighed. Kopiér den direkte til den sikrede Bitbucket-variabel, og undgå logs og commits.

Ændringer i templates

Ved ændring af en src/setup/bitbucket-pipelines.*.yml skal datoen i dens versionskommentar opdateres manuelt før commit:

# ecreo-version: umbraco-cloud.2026-10-20

Formatet er <variant>.<YYYY-MM-DD>. Publiceringen stempler ikke versionen automatisk. Runneren sammenligner projektets kommentar med den publicerede template og kan på main foreslå en opdaterings-PR. Se Synkronisering og vedligeholdelse.

Brug Bitbuckets YAML-templating i concurrency-grupper, eksempelvis ${{BITBUCKET_BRANCH}}. Repositorynavnet sammensættes af ${{BITBUCKET_WORKSPACE}}/${{BITBUCKET_REPO_SLUG}}, da BITBUCKET_REPO_FULL_NAME ikke er tilgængelig i denne templating.

Branchvalget til automatisk deployment ligger i top-level triggers.repository-push. Bevar branchbetingelserne dér, så manuelle deployments fortsat kan bruge en valgfri branch. Tilføj ikke parallelle branch/default-deployment-selektorer, som kan give dobbelte kørsler.

Når ændringen er klar

Kontrollér de berørte tests, eventuelle kopier af hjælpefiler, template-datoer og dokumentation. Opdatér relevante sider i docs-site/src/content/docs/ ved brugerrettede ændringer.

Ændringer i runner og grupper når projekterne ved næste kørsel efter publicering. Et lokalt override i et projekt kan dog fortsat skjule en central rettelse. Projektets YAML-fil opdateres separat via template-PR eller manuel sammenligning.

Dokumentationssitet er den fælles kilde til projekt- og udviklervejledninger. Ændringer publiceres til Azure Static Web Apps fra repositoryets pipeline. Se Udvikling af dokumentationssitet for lokal preview, build og deployment.

Tilbage til oversigten.