Udrulningsmiljøer

Miljøer er navngivne udrulningsmål (f.eks. staging, production, eu-west) med sikkerhedsgates, der kan kombineres. Et workflow-job, der erklærer environment: production, vurderes mod ALLE konfigurerede gates, før fremforge opretter runner-VM’en. Fejler bare én gate, afvises udrulningen med en struktureret årsag. Organisationens administratorer behandler sagen i administrationen, og workflowet kan køres igen, når den underliggende betingelse er løst.

Hurtig start

1. Gå til fremforge-administration → Miljøer (https://frem.sh/<org>/_admin/environments).

2. Under Nyt miljø skriver du et navn og klikker på Opret.

3. Åbn det nye miljøs detaljeside, rul ned til Udrulningspolitikker, konfigurér de politikker, du vil have, og klik på Gem politikker.

4. Henvis til miljøet i et vilkårligt workflow-job:

   jobs:
     deploy:
       runs-on: fremforge
       environment: production
       steps:
         - run: ./deploy.sh

Den næste udrulning til miljøet vurderes mod dine gates.

De 9 gates

Alle gates er uafhængige og kan kombineres. ALLE konfigurerede gates skal BESTÅ, før en udrulning kan fortsætte. En gate uden konfiguration springes over (regnes som bestået).

A. Påkrævede godkendere

Stop afsendelsen, indtil N personer har klikket på Godkend på den ventende udrulning.

• Hvornår: produktionsudrulninger, regulerede miljøer og alt andet, hvor et ekstra sæt øjne er sikkerhedsnettet.
• Konfiguration: Påkrævede godkendere på miljøets detaljeside. 0 = ingen godkendelse; 1–6 = N godkendere kræves.
• Hvor du godkender: fremforge-administration → Udrulninger (/<org>/_admin/deployments), afsnittet “Ventende godkendelser”.
• Bemærk: den bruger, der udløste workflowet (personen, der pushede committen eller åbnede pull requesten), kan ikke godkende sin egen udrulning. Platformen afviser selvgodkendelse både i route-laget og i evalueringen.
• Tilbagekaldelse: godkendere kan tilbagekalde deres egen godkendelse, før udrulningen sendes afsted (f.eks. hvis du opdager et problem efter at have klikket på Godkend). Når udrulningen er sendt afsted, kan godkendelsen ikke ændres.

B. Tilladte refs (branch- og tag-mønstre)

Begræns, hvilke git-refs der må udrulle til miljøet.

• Hvornår: “kun main udruller til produktion”; “kun release/*-tags udruller til canary”.
• Konfiguration: Branches og tags til udrulning på miljøets detaljeside. Globs i GitHub-stil: main, release/*, **/hotfix-*, refs/tags/v[0-9]+.*. Tomt = alle refs er tilladt.

C. Tidsvindue

Begræns udrulninger til bestemte arbejdstider, eller spær dem under frys.

• Hvornår: “kun udrulning man–tor 09:00–17:00 CET”; “spær alle udrulninger 22. dec. – 2. jan. (julefrys)”.

• Konfiguration: Tidsvindue som JSON på miljøets detaljeside. Format:

  {
    "tz": "Europe/Copenhagen",
    "allowed": [
      { "days": ["Mon", "Tue", "Wed", "Thu"], "from": "09:00", "to": "17:00" }
    ],
    "blackouts": [
      { "from": "2026-12-22T00:00Z", "to": "2027-01-02T00:00Z", "reason": "holiday freeze" }
    ]
  }
  • tz: IANA-tidszone. Standard er UTC.
  • allowed: en liste over tilladte vinduer. Dage skrives med tre engelske bogstaver (Mon..Sun). Tidspunkter er 24-timers HH:MM i tz.
  • blackouts: en liste over absolutte UTC-intervaller, hvor udrulning er forbudt uanset allowed.

• Bemærk: blackouts går forud for allowed. Tomt = ingen tidsbegrænsning.

D. Sundt SLO-budget

Afvis udrulninger, mens SLO-fejlbudgettet bliver brugt op.

• Hvornår: “udrul ikke, mens kundevendt latenstid eller fejlrate er i rødt – ret regressionen først.”
• Konfiguration: Spær, når disse alarmer er udløst – kommaseparerede navne på CES/LTS-alarmer, som dine burn-rate-watchdogs vedligeholder. Eksempel: my-api-latency-sev1, my-api-error-budget-sev2.
• Sådan virker det: fremforge følger den seneste tilstand for hver angivet alarm. Er en af dem i tilstanden firing, afviser denne gate afsendelsen.
• Fail-closed: har fremforge ingen nylig tilstand for en angivet alarm, fejler gaten lukket – en undersøgelse er at foretrække frem for en stille omgåelse.

E. Påkrævede statustjek

Kræv, at navngivne Forgejo commit-status-kontekster er success på den commit, der udrulles.

• Hvornår: “udrulninger skal vente, til dep-scan, SAST og image-scan alle er bestået på denne commit.”
• Konfiguration: Påkrævede tjek-kontekster – én pr. linje. Eksempler: dep-scan, sast, sha-pin-scan, image-scan-trivy.
• Sådan virker det: fremforge læser GET /api/v1/repos/<o>/<r>/statuses/<sha> under preflight. Hver påkrævet kontekst skal have tilstanden success. Manglende tilstande og alle andre tilstande end success får gaten til at fejle.

F. Samtidighedslås

Sæt et loft over antallet af igangværende udrulninger til miljøet.

• Hvornår: “kun én produktionsudrulning ad gangen” – forhindrer race conditions, hvor to udrulninger overskriver hinanden.
• Konfiguration: Maks. igangværende udrulninger – heltal 0–100. 0 = intet loft.
• Tæller med: tilstandene pending_gates, pending_approval og dispatched. Et forsøg i tilstanden completed eller failed tæller ikke længere.

G. Karantæne efter rollback

Spær udrulninger i N minutter efter en rollback, så teamet kan undersøge sagen.

• Hvornår: “efter en rollback, gennemtving 60 minutters pause før ny udrulning” – forhindrer, at den samme regression ved et uheld udløses igen.
• Konfiguration: Karantæne efter rollback (minutter) – heltal 0–1440 (24 t). 0 = ingen karantæne.

H. Tilknyttet sag påkrævet

Kræv, at beskrivelsen af den pull request, der udrulles, henviser til en issue eller en hændelsessag.

• Hvornår: krav om compliance eller audit-spor – hver produktionsudrulning skal have et “hvorfor” knyttet til sig.
• Konfiguration: slå Kræv en sagshenvisning i PR-beskrivelsen til. Du kan eventuelt erstatte standardmønsteret med et regulært udtryk i Sagsmønster.
• Standardmønster: (?i)(JIRA|FF|INC|FIX)-[0-9]+|fixes? #[0-9]+|closes? #[0-9]+|resolves? #[0-9]+ – matcher JIRA-1234, FF-99, fixes #42, Closes #99 osv. Præfikset (?i) gør det uafhængigt af store og små bogstaver.
• Eget mønster pr. tenant: ethvert gyldigt regulært udtryk i JavaScript. Præfikset (?i) respekteres.

I. Pauseflag

En kontakt pr. miljø, der stopper alle udrulninger.

• Hvornår: under en hændelse. Sæt en pause, undersøg, og ryd den igen.
• Konfiguration: Pr. miljø (tenant-administration): <org>/_admin/deployments → afsnittet “Pauseflag”. fremforge kan også sætte en pause for hele platformen under en hændelse; enhver aktiv pause, der dækker dit miljø, spærrer udrulningen.
• Afgørelse: det mest specifikke scope bestemmer årsagsfeltet, men ETHVERT aktivt scope spærrer udrulningen.

Sådan forløber en evaluering

Når platformen samler et workflow med environment: <name> op:

1. Preflight – fremforge slår miljøet op for tenanten. Intet miljø konfigureret = ingen gates gælder (doven onboarding: nye kunders workflows blokeres ikke, før de har konfigureret miljøer).
2. Opret eller find et udrulningsforsøg med nøglen (env, ref, commit_sha). Nye afsendelser af det samme workflow mod den samme commit deler forsøg – så et godkendelsesforløb overlever genforsøg.
3. Indhent oplysninger – aktørens e-mail og pull requestens beskrivelse læses fra Forgejo. Det sker efter bedste evne, med syntetiske værdier som reserve, hvis Forgejo er nedsat.
4. Evaluér alle 9 gates parallelt – hver gate er uafhængig og læser sit eget signal.
5. Saml resultatet – består ALLE konfigurerede gates, skifter status til dispatched, og runner-VM’en oprettes. Fejler KUN gate A (godkendere), skifter status til pending_approval – administratorer kan klikke på Godkend, og næste genforsøg evaluerer igen. Fejler en anden gate, skifter status til gates_failed.
6. Audit – hele opgørelsen af gate-resultaterne registreres, og der udsendes en audit-hændelse.

Sådan ser en afvist udrulning ud

Kunden ser: workflow-kørslen er annulleret, med et commit-statustjek, der viser årsagen til afvisningen (f.eks. deploy_gate_C_time_window — outside allowed windows).

Organisationens administrator ser: en række under Ventende udrulninger med hele evalueringen – hvilke gates der bestod, og hvilke der fejlede, med den konkrete reason-tekst for hver gate.

Hvad der kører i hvert miljø

fremforge-administration → Udrulninger (https://frem.sh/<org>/_admin/deployments) starter med Live pr. miljø. For hvert miljø vises den udrulning, der kører nu, og den før den, som er det, du kan rulle tilbage til:

• repository, ref (branch eller tag) og commit, med link;
• de tags, der peger på commitet, for eksempel prd-2026-11-01 eller rc-81;
• hvem der godkendte den, og hvornår;
• hvornår udrulningen blev gennemført, og et link til dens workflow-kørsel.

En udrulning tæller kun som live, når dens kørsel blev startet og gennemført uden fejl. Fejlede, annullerede, afviste og ventende forsøg tæller aldrig med, så efter en fejlet udrulning står den forrige stadig som live. Et miljø uden en gennemført udrulning viser Aldrig udrullet.

Release-værktøjer kan læse de samme data fra API’et med et token, der har deployments:read, så de ikke skal læse siden:

curl -fsS "https://frem.sh/_app/api/v1/orgs/acme/deployments/live?environment=production" \
  -H "Authorization: Bearer $FREMFORGE_TOKEN"

Hvert miljø i svaret har live og previous, og begge er null, indtil der er udrullet noget. Hver af dem har repo_full_name, ref, commit_sha, commit_url, tags, approvals, deployed_at, run_number og run_url. Udelad ?environment= for at få alle miljøer. tags læses fra repositoryets nyeste 150 tags og kan være op til et minut gamle. Feltet er null (ikke []), når tags ikke kunne læses i øjeblikket.

Kombination af gates

Stigen kan bevidst kombineres – de fleste kunder konfigurerer 2–3 gates pr. miljø, ikke alle 9. Forslag til et udgangspunkt:

Start småt – tilføj gates, efterhånden som du vokser.

Secrets og variabler pr. miljø

Uafhængigt af gates har miljøer deres egne secrets og variabler, som kun sendes ind i jobs, der erklærer environment: <name>. Se Secrets for, hvordan secrets håndteres.

Administration af miljøer via API’et

Alt, hvad administrationen kan, kan REST-API’et også. Miljøer ligger i fremforge-extension-navnerummet, så basis-URL’en er https://frem.sh/_app/api/v1 – ikke den bare /api/v1, som er Forgejos eget API og vil afvise kaldet.

Miljønavne skal matche [A-Za-z0-9_.-]+ (ingen /). Variabelnavne skal matche [A-Z][A-Z0-9_]*, og værdier må fylde op til 64 KiB. Secret-værdier krypteres i hvile og returneres aldrig – list-endpoints giver kun navne og metadata.

# Create an environment, then give it a variable and a secret.
curl -fsS -X POST https://frem.sh/_app/api/v1/orgs/acme/environments \
  -H "Authorization: Bearer $FREMFORGE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"name":"staging"}'

curl -fsS -X PUT https://frem.sh/_app/api/v1/orgs/acme/environments/staging/variables/REGION \
  -H "Authorization: Bearer $FREMFORGE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"value":"eu-de"}'

curl -fsS -X PUT https://frem.sh/_app/api/v1/orgs/acme/environments/staging/secrets/DEPLOY_KEY \
  -H "Authorization: Bearer $FREMFORGE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"value":"…"}'

Hvis du får en 403

403 Token lacks required scope 'environments:…' betyder, at endpointet findes, men at dit token ikke har scopet – det er ikke en manglende funktion. Tjek, hvilke scopes din legitimationsoplysning faktisk har. Et PAT, du selv har oprettet, har præcis de scopes, du krydsede af; en dev bench har et sæt, som platformen udsteder, som bevidst er snævrere og fornyes, når benchen vågner.

OIDC-claim for miljøet

Workflows, der erklærer environment: <name>, får en ekstra OIDC-claim – sub bliver repo:<owner>/<repo>:environment:<name>. Det er den, cloududbydernes trust policies matcher på ved kortlivet føderation (AWS STS AssumeRoleWithWebIdentity, Azure WIF, GCP Workload Identity Federation). Se OIDC-føderation for, hvordan trust policies skal se ud.

Fejlfinding

Workflowet hænger på “Review pending”, og der er ikke sendt nogen notifikation. → Tjek miljøets antal Påkrævede godkendere. Godkendelser sker på administrationssiden Ventende udrulninger; fremforge sender (endnu) ikke e-mail til godkenderne. Tilføj siden til teamets morgenmøde.

En udrulning blev afvist med deploy_gate_D_slo_burn, men jeg har ikke konfigureret gate D. → Gate D fejler lukket, når fremforge ikke har nogen nylig tilstand for en angivet alarm. Har du ANGIVET et alarmnavn, der aldrig har rapporteret en tilstand, afviser gaten automatisk. Fjern alarmnavnet fra gatens konfiguration, eller sørg for, at alarmen er sat op, så dens tilstand bliver rapporteret.

Pull requestens beskrivelse matcher et sagsmønster, men gate H fejler stadig. → Udrulningsforsøget blev oprettet, FØR pull requesten blev åbnet. fremforge gemmer beskrivelsen ved første evaluering og henter den ikke igen. Push en tom commit for at udløse en ny evaluering.

Jeg vil midlertidigt omgå mine gates. → Der er endnu ingen brugerflade til omgåelse pr. tenant. Kontakt support@frem.sh for midlertidigt at omgå en gate. Pauseflagenes scopes er kun til/fra-kontakter (ryd/aktiv).

Audit-hændelser

Hver gate-afgørelse udsender strukturerede audit-hændelser: