Utrullingsmiljøer

Miljøer er navngitte utrullingsmål (f.eks. staging, production, eu-west) med kombinerbare sikkerhetssperrer. En workflow-jobb som deklarerer environment: production, vurderes mot ALLE konfigurerte sperrer før fremforge klargjør runner-VM-en – hvis en sperre feiler, avvises utrullingen med en strukturert begrunnelse. Organisasjonsadministratorer følger opp i administrasjonsgrensesnittet; workflowen kan kjøres på nytt når den underliggende tilstanden er løst.

Hurtigstart

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

2. Under Nytt miljø skriver du inn et navn og klikker på Opprett.

3. Åpne detaljsiden for det nye miljøet, bla ned til Utrullingsregler, sett opp policyene du vil ha, og klikk på Lagre regler.

4. Referer til miljøet i en hvilken som helst workflow-jobb:

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

Den neste utrullingen mot dette miljøet blir vurdert mot sperrene dine.

De 9 sperrene

Alle sperrene er uavhengige og kan kombineres. ALLE konfigurerte sperrer må BESTÅ for at en utrulling skal gå videre. En sperre uten konfigurasjon hoppes over (regnes som bestått).

A. Påkrevde godkjennere

Stopper utsendingen til N personer har klikket på Godkjenn på den ventende utrullingen.

• Når den brukes: produksjonsutrullinger, regulerte miljøer, alt der et ekstra par øyne er sikkerhetsnettet.
• Konfigurer: Required reviewers på detaljsiden for miljøet. 0 = ingen godkjenning; 1–6 = N godkjennere påkrevd.
• Hvor du godkjenner: Organisasjonsadministrasjon → Utrullinger (/<org>/_admin/deployments), avsnittet «Ventende godkjenninger».
• Merknader: brukeren som utløste workflowen (personen som pushet commiten / åpnet PR-en), kan ikke godkjenne sin egen utrulling. Plattformen avviser selvgodkjenning både i ruten og i evalueringen.
• Tilbakekalling: godkjennere kan tilbakekalle sin egen godkjenning før utrullingen sendes ut (f.eks. hvis du oppdaget et problem etter å ha klikket på Approve). Når utrullingen er sendt ut, kan godkjenningen ikke endres.

B. Tillatte refs (branch- / tag-mønstre)

Begrenser hvilke git-refs som kan rulles ut til dette miljøet.

• Når den brukes: «bare main rulles ut til produksjon»; «bare release/*-tagger rulles ut til canary».
• Konfigurer: Deployment branches and tags på detaljsiden for miljøet. Glob-mønstre i GitHub-stil: main, release/*, **/hotfix-*, refs/tags/v[0-9]+.*. Tomt = alle refs er tillatt.

C. Tidsvindu

Begrenser utrullinger til bestemte arbeidstider eller blokkerer dem i frysperioder.

• Når den brukes: «utrullinger bare man–tor 09:00–17:00 CET»; «blokker alle utrullinger 22. des – 2. jan (frys i høytiden)».

• Konfigurer: Time-window JSON på detaljsiden for miljøet. Form:

  {
    "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-tidssone. Standard er UTC.
  • allowed: liste over tillatte vinduer. Dager skrives med 3 bokstaver (Mon..Sun). Tider er 24-timers HH:MM i tz.
  • blackouts: liste over absolutte UTC-intervaller der utrullinger er forbudt uansett allowed.

• Merknader: blackouts har forrang foran allowed. Tomt = ingen tidsbegrensning.

D. Sunt SLO-budsjett

Avviser utrullinger mens SLO-feilbudsjettet brennes opp.

• Når den brukes: «ikke rull ut mens kundevendt ventetid eller feilrate er i rødt – rett regresjonen først».
• Konfigurer: Block when these alarms are firing – kommaseparerte navn på CES-/LTS-alarmer som burn-rate-vaktene dine vedlikeholder. Eksempel: my-api-latency-sev1, my-api-error-budget-sev2.
• Slik virker den: fremforge følger den siste tilstanden til hver oppført alarm. Når en oppført alarm er i tilstanden firing, avviser denne sperren utsendingen.
• Feiler lukket: hvis fremforge ikke har noen nylig tilstand for en oppført alarm, feiler sperren lukket – det er bedre å undersøke enn å slippe gjennom i det stille.

E. Påkrevde statussjekker

Krever at navngitte commit-statuskontekster i Forgejo er success på commiten som rulles ut.

• Når den brukes: «utrullinger må vente til dep-scan, SAST og image-scan har bestått på denne commiten».
• Konfigurer: Required check contexts – én per linje. Eksempler: dep-scan, sast, sha-pin-scan, image-scan-trivy.
• Slik virker den: fremforge leser GET /api/v1/repos/<o>/<r>/statuses/<sha> ved forhåndskontrollen. Hver påkrevde kontekst må rapportere tilstanden success. Manglende tilstander ELLER andre tilstander enn success får sperren til å feile.

F. Samtidighetslås

Setter et tak på antall pågående utrullinger til dette miljøet.

• Når den brukes: «bare én produksjonsutrulling om gangen» – hindrer kappløpssituasjoner der to utrullinger ødelegger for hverandre.
• Konfigurer: Max in-flight deploys – heltall 0–100. 0 = ingen grense.
• Teller: tilstandene pending_gates, pending_approval og dispatched. Et forsøk som er completed eller failed, teller ikke lenger.

G. Avkjølingstid etter tilbakerulling

Etter en tilbakerulling blokkeres utrullinger i N minutter, slik at teamet kan undersøke.

• Når den brukes: «etter en tilbakerulling, tving en pause på 60 minutter før ny utrulling» – hindrer at den samme regresjonen utløses på nytt ved et uhell.
• Konfigurer: Cooldown after rollback (minutes) – heltall 0–1440 (24 t). 0 = ingen avkjølingstid.

H. Krav om tilknyttet ticket

Krever at beskrivelsen i PR-en som rulles ut, refererer til en ticket eller hendelse.

• Når den brukes: krav til etterlevelse / revisjonsspor – hver produksjonsutrulling må ha en «hvorfor» knyttet til seg.
• Konfigurer: kryss av for Require PR body to reference an issue/incident ticket. Eventuelt et eget regex i Ticket pattern.
• 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. Prefikset (?i) gjør det uavhengig av store og små bokstaver.
• Overstyring per organisasjon: et hvilket som helst gyldig JavaScript-regex. Prefikset (?i) respekteres.

I. Pauseflagg

En bryter per miljø som stanser alle utrullinger.

• Når den brukes: under en hendelse. Sett en pause; undersøk; fjern den.
• Konfigurer: Per miljø (organisasjonsadministrasjonen): <org>/_admin/deployments → avsnittet «Pause flags». fremforge kan også sette en pause for hele plattformen under en hendelse; enhver aktiv pause som dekker miljøet ditt, blokkerer utrullingen.
• Avgjørelse: det mest spesifikke nivået vinner for begrunnelsesfeltet, men ETHVERT aktivt nivå blokkerer utrullingen.

Slik kjøres en evaluering

Når en workflow med environment: <name> plukkes opp av plattformen:

1. Forhåndskontroll – fremforge slår opp miljøet for organisasjonen. Ingen konfigurerte miljøer = ingen sperrer gjelder (gradvis innføring; workflowene til nye kunder blokkeres ikke før de har satt opp miljøer).
2. Opprett eller finn et utrullingsforsøk med nøkkelen (env, ref, commit_sha). Nye utsendinger av den samme workflowen mot den samme commiten deler samme forsøk – så en godkjenningsflyt varer på tvers av nye forsøk.
3. Hent grunnlagsdata – aktørens e-postadresse og PR-beskrivelsen leses fra Forgejo. Etter beste evne; faller tilbake til syntetiske verdier hvis Forgejo har redusert drift.
4. Evaluer alle 9 sperrene parallelt – hver sperre er uavhengig og leser sitt eget signal.
5. Sett sammen – hvis ALLE konfigurerte sperrer består, skifter statusen til dispatched, og runner-VM-en klargjøres. Hvis BARE sperre A (godkjennere) feiler, skifter statusen til pending_approval – administratorer kan klikke på Approve, og neste forsøk evaluerer på nytt. Hvis en annen sperre feiler, skifter statusen til gates_failed.
6. Revisjon – hele oversikten over sperreresultatene registreres, og en revisjonshendelse sendes.

Slik ser en avvist utrulling ut

Kunden ser: workflow-kjøringen er avbrutt, med en commit-statussjekk som viser begrunnelsen for avvisningen (f.eks. deploy_gate_C_time_window — outside allowed windows).

Organisasjonsadministratoren ser: en rad under Pending deployments med hele evalueringen – hvilke sperrer som besto og hvilke som feilet, med den konkrete reason-strengen per sperre.

Hva som kjører i hvert miljø

Organisasjonsadministrasjon → Utrullinger (https://frem.sh/<org>/_admin/deployments) starter med Live per miljø. For hvert miljø vises utrullingen som kjører nå, og den før den, som er målet ditt for en tilbakerulling:

• repository, ref (branch eller tag) og commit, med lenke;
• taggene som peker på commiten, for eksempel prd-2026-11-01 eller rc-81;
• hvem som godkjente den, og når;
• når utrullingen ble fullført, og en lenke til workflow-kjøringen.

En utrulling regnes bare som live når kjøringen ble startet og fullført uten feil. Mislykkede, avbrutte, avviste og ventende forsøk teller aldri, så etter en mislykket utrulling står den forrige fortsatt som live. Et miljø uten noen fullført utrulling viser Aldri rullet ut.

Release-verktøy kan lese de samme dataene fra API-et med et token som har deployments:read, uten å lese 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 til noe er rullet ut der. Hver av dem har repo_full_name, ref, commit_sha, commit_url, tags, approvals, deployed_at, run_number og run_url. Utelat ?environment= for å få alle miljøer. tags leses fra de 150 nyeste taggene i repositoryet og kan være opptil ett minutt gamle. Feltet er null (ikke []) når taggene ikke kunne leses akkurat da.

Kombinere sperrer

Stigen er laget for å kombineres – de fleste kunder setter opp 2–3 sperrer per miljø, ikke alle 9. Foreslåtte utgangspunkt:

Begynn i det små – legg til sperrer etter hvert som organisasjonen vokser.

Secrets og variabler per miljø

Uavhengig av sperrene har miljøer sine egne secrets og variabler, som bare legges inn i jobber som deklarerer environment: <name>. Se Secrets for hvordan secrets håndteres.

Administrere miljøer via API-et

Alt administrasjonsgrensesnittet gjør, gjør også REST-API-et. Miljøer ligger i navnerommet fremforge-extension, så basis-URL-en er https://frem.sh/_app/api/v1 – ikke bare /api/v1, som er Forgejos eget API og vil avvise kallet.

Miljønavn må matche [A-Za-z0-9_.-]+ (ingen /). Variabelnavn må matche [A-Z][A-Z0-9_]*, med verdier på opptil 64 KiB. Secret-verdier krypteres ved lagring og returneres aldri – listeendepunktene gir bare navn 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 403

403 Token lacks required scope 'environments:…' betyr at endepunktet finnes, men at tokenet ditt ikke har scopet – det er ikke en manglende funksjon. Sjekk hvilke scopes legitimasjonen din faktisk har. Et PAT du har utstedt selv, har nøyaktig de scopene du krysset av for; en utviklingsbench har et sett utstedt av plattformen som med vilje er smalere og fornyes når benchen våkner.

OIDC-claim for miljøet

Workflower som deklarerer environment: <name>, får en ekstra OIDC-claim – sub blir repo:<owner>/<repo>:environment:<name>. Det er dette tillitspolicyer i skyen matcher på for kortlivet føderasjon (AWS STS AssumeRoleWithWebIdentity, Azure WIF, GCP Workload Identity Federation). Se OIDC-føderasjon for formene på tillitspolicyene.

Feilsøking

Workflowen står fast på «Review pending», og det ble ikke sendt noe varsel. → Sjekk antallet under Required reviewers for miljøet. Godkjenninger skjer på administrasjonssiden Pending deployments; fremforge sender (ennå) ikke e-post til godkjennere. Legg siden inn i teamets daglige morgenmøte.

En utrulling ble avvist med deploy_gate_D_slo_burn, men jeg har ikke konfigurert sperre D. → Sperre D feiler lukket når fremforge ikke har noen nylig tilstand for en oppført alarm. Har du FØRT OPP et alarmnavn som aldri har rapportert noen tilstand, avviser sperren automatisk. Fjern alarmnavnet fra konfigurasjonen av sperren, eller sørg for at alarmen er koblet opp slik at tilstanden rapporteres.

PR-beskrivelsen matcher et ticket-mønster, men sperre H feiler likevel. → Utrullingsforsøket ble opprettet FØR PR-en ble åpnet. fremforge fanger PR-beskrivelsen ved første evaluering og henter den ikke på nytt. Push en tom commit for å utløse en ny evaluering.

Jeg vil omgå sperrene midlertidig. → Det finnes ennå ikke noe grensesnitt for å omgå sperrer per organisasjon. Kontakt support@frem.sh for å omgå en sperre midlertidig. Nivåene for pauseflagg er bare brytere for fjernet/aktiv.

Revisjonshendelser

Hver beslutning i en sperre sender strukturerte revisjonshendelser: