Secrets og miljøvariabler

Secrets er krypterte verdier som legges inn i workflow-jobber som miljøvariabler. De kan bare skrives etter at de er opprettet. Verdien kan aldri leses tilbake gjennom brukergrensesnittet eller API-et. Denne siden dekker omfang, oppretting, bruk i workflower, rotasjon og grenser.

Secrets krypteres ved lagring med T Cloud Public DEW KMS og dekrypteres først når jobben kjører på runneren.

Secrets på organisasjonsnivå administreres i organisasjonsadministrasjonen på frem.sh/<org>/_admin/secrets. Secrets på repository-nivå ligger under Innstillinger → Actions → Secrets i hvert repository i Forgejo. Miljøer, med sine secrets, variabler, branch-regler og godkjennere, administreres i organisasjonsadministrasjonen på frem.sh/<org>/_admin/environments. fremforge gir en jobb miljøets secrets når jobben tildeles en runner, og bruker rangeringen (miljø, deretter repository, deretter organisasjon) der.

Omfang

Rangering: en miljø-secret overstyrer en avgrenset secret knyttet til et repository, som overstyrer en avgrenset secret for hele organisasjonen, som overstyrer en repository-secret, som overstyrer en organisasjons-secret. Når det samme navnet finnes på flere nivåer, vinner det mest spesifikke.

Opprette secrets

Via brukergrensesnittet: gå til riktig nivå, bla ned til Legg til eller oppdater en secret, skriv inn navn (konvensjonen er UPPER_SNAKE_CASE) og verdi, og klikk på Lagre secret.

Via API-et:

# Org secret
curl -X PUT \
  -H "Authorization: Bearer <PAT>" \
  -H "Content-Type: application/json" \
  -d '{"name":"MY_SECRET","data":"the-value"}' \
  https://frem.sh/_app/api/v1/orgs/<org>/actions/secrets/MY_SECRET

# Repo secret
curl -X PUT \
  -H "Authorization: Bearer <PAT>" \
  -H "Content-Type: application/json" \
  -d '{"name":"MY_SECRET","data":"the-value"}' \
  https://frem.sh/api/v1/repos/<org>/<repo>/actions/secrets/MY_SECRET

Secrets kan bare skrives etter at de er opprettet. Du kan ikke lese tilbake verdien til en secret gjennom API-et eller brukergrensesnittet. Du kan bare overskrive eller slette.

Bruke secrets i workflower

Referer til secrets med ${{ secrets.NAME }}. Secrets er tilgjengelige som miljøvariabler.

env:
  DATABASE_URL: ${{ secrets.DATABASE_URL }}

steps:
  - name: Deploy
    env:
      API_KEY: ${{ secrets.DEPLOY_API_KEY }}
    run: ./deploy.sh

Secrets maskeres i logger: all loggutdata som nøyaktig samsvarer med verdien til en secret, erstattes med ***. Maskeringen gjelder bare nøyaktige treff; base64-kodede, URL-kodede eller på andre måter omformede varianter av verdien maskeres ikke automatisk.

Miljø-secrets og sperrer for utrulling

Jobber som deklarerer environment:, får bare secrets som er avgrenset til det miljøet (pluss repository- og organisasjons-secrets). Dette er med vilje: miljø-secrets plasserer produksjonslegitimasjon bak miljøets godkjenningsflyt.

jobs:
  deploy-prod:
    runs-on: fremforge
    environment: production   # triggers approval gate if reviewers are configured
    steps:
      - name: Deploy
        env:
          DB_URL: ${{ secrets.PROD_DB_URL }}   # environment secret on 'production'
        run: ./deploy.sh

Sett opp påkrevde godkjennere under Organisasjonsadministrasjon → Miljøer → <env>. Jobben venter på godkjenning før steget kjører; secreten legges ikke inn før jobben er godkjent og kjører.

Miljønavn matches uten hensyn til store og små bokstaver, som i Forgejo og GitHub: environment: Production er miljøet production, med sin branch-regel, sine godkjennere og sine secrets. Hvis to miljøer bare skiller seg fra hverandre med store og små bokstaver, brukes det som er stavet nøyaktig slik jobben deklarerer det; hvis ingen av dem er det, får jobben ikke noe miljø, og utrullingssperren avviser den (environment_case_ambiguous). Gi ett av dem nytt navn.

En pull_request_target-kjøring fra en fork får ikke noe miljø, ingen av miljøets secrets og ingen OIDC-claim for det, uansett hva jobben deklarerer. Dette er strengere enn GitHub. Se Rekkevidden til secrets i PR-er fra forks.

Miljø-secrets når bare jobbene som refererer til dem

Siden 2026-10-26 får en jobb en miljø-secret bare når jobben refererer til den: i sine egne steg, env:, with: eller if:, eller i env: på workflow-nivå, som ${{ secrets.NAME }} eller ${{ secrets['NAME'] }}. En secret som jobben ikke refererer til, sendes ikke til runneren i det hele tatt, så den finnes ikke på maskinen jobben kjører på.

${{ toJSON(secrets) }}, et beregnet navn som ${{ secrets[format('{0}_KEY', 'DEPLOY')] }} og secrets: inherit i et kall til en gjenbrukbar workflow refererer til alle secretene i miljøet, som på GitHub.

Et steg kan bare lese en secret gjennom et slikt uttrykk, så en workflow som virker i dag, fortsetter å virke: endringen fjerner secrets som ingen steg kunne lese.

Hvis fremforge ikke kan lese jobbens workflow-fil på jobbens commit, eller ikke finner jobben i den, får jobben ingen av miljøets secrets. Jobben kjører likevel, med OIDC-tokenet og variablene sine.

Hvem fikk hvilken secret: revisjon av lesing

Hver CI-jobb som får en miljø-secret eller en avgrenset secret, eller som refererer til en den blir nektet, skriver én oppføring i organisasjonens revisjonslogg, med handlingen ci.secret.read:

Verdien til en secret registreres aldri, heller ikke en hash av den. En jobb som ikke refererer til noen av miljøets secrets, får ingen og skriver ingen oppføring.

Oppføringen skrives før secretene gis til runneren. Hvis den ikke kan lagres, får jobben ingen av dem: ingen secret forlater fremforge uten å bli registrert. fremforges vakt blir varslet når det skjer.

Hent oppføringene med API-et:

curl -H "Authorization: Bearer $FREMFORGE_TOKEN" \
  "https://frem.sh/_app/api/v1/orgs/<org>/audit?action=ci.secret.read&since=2026-10-26"

Oppføringene er en del av revisjonsloggens hash-kjede, oppbevaring og SIEM-strøm, som alle andre revisjonsoppføringer.

Repository- og organisasjons-secrets som er satt i Forgejo, dekkes ikke: Forgejo gir dem fortsatt til alle jobber i repositoryet, og lesingen av dem registreres ikke. Bruk heller en avgrenset CI-secret, og slett Forgejo-kopien med samme navn: så lenge den finnes, når den fortsatt jobbene som omfanget avviser.

Avgrensede CI-secrets

En avgrenset CI-secret holdes av fremforge, for hele organisasjonen eller for ett repository, og gis til en jobb bare når alle feltene du har satt i omfanget, matcher (innenfor et felt holder det at én av de oppførte verdiene matcher):

* er det eneste jokertegnet. Et felt du utelater, slipper gjennom alt, med ett unntak: uten oppførte events får en kjøring på en pull requests ref (refs/pull/...) aldri secreten. For å gi kode i en pull request en avgrenset secret må du føre opp pull_request (eller pull_request_target) eksplisitt.

Jobben må også referere til secreten (som over). Hver levering, og hver avvisning av en secret jobben refererte til, registreres i jobbens ci.secret.read-oppføring. En pull request fra en fork får aldri en.

Hvilke felt som er en sikkerhetsgrense. Alle som kan pushe til repositoryet, kan opprette en branch der workflowen har en jobb med navnet deploy i en fil med navnet deploy.yaml, og starte den. workflows og jobs begrenser derfor hvilke kodestier som normalt får secreten, men de beskytter den ikke mot personer med skrivetilgang. Det gjør refs (pek den mot beskyttede brancher eller tagger) og environment (med en branch-regel og påkrevde godkjennere). Det er det samme som på GitHub.

En kjøring i merge-køen (refs/heads/fremforge-queue/...) er et bygg i samme repository som en vedlikeholder har satt i kø, og et tomt refs-omfang slipper den gjennom, som enhver branch. Begrens refs hvis en secret ikke skal nå kjøringer i merge-køen.

Jobber i en gjenbrukbar workflow – og, på en Forgejo-versjon som ennå ikke sender jobb-ID-en, jobber med egen name: eller en matrise – får ennå ikke avgrensede secrets.

Opprett eller erstatt en (verdien kan bare skrives; hver endring revideres, sammen med omfanget den erstattet):

curl -X PUT -H "Authorization: Bearer $FREMFORGE_TOKEN" -H 'Content-Type: application/json' \
  -d '{"value":"...","workflows":["deploy.yaml"],"jobs":["deploy"],"refs":["refs/heads/main"],"events":["push","workflow_dispatch"]}' \
  "https://frem.sh/_app/api/v1/orgs/<org>/ci-secrets/DEPLOY_KEY?repository_id=<forgejo repository id>"

Utelat repository_id for en secret for hele organisasjonen. Et ukjent felt, et environment som ikke er et navn, og en tom oppføring i en liste avvises (400) i stedet for å bli ignorert, slik at en skrivefeil aldri kan utvide en secret til alle jobber. GET /orgs/<org>/ci-secrets lister navn, omfang og når hver av dem sist ble lest; DELETE .../ci-secrets/<NAME>[?repository_id=] fjerner én. Scopes: ci-secrets:read, ci-secrets:write. Grenser: 500 per organisasjon, 100 per repository, 20 mønstre per felt, 64 KB per verdi.

Vil du styre scoped CI-secrets som kode, bruk fremforge_ci_secret i fremforge-provideren (fra 0.9.0). Verdien er et write-only-argument og når aldri Terraform-state.

Rotasjon av secrets

1. Opprett den nye legitimasjonen i det eksterne systemet først.
2. Overskriv secreten i fremforge med den nye verdien. Ikke slett og opprett på nytt.
3. Start en ny workflow-kjøring for å bekrefte at den nye legitimasjonen virker hele veien.
4. Tilbakekall den gamle legitimasjonen i det eksterne systemet.

Overskriving tar vare på revisjonssporet og unngår et tidsvindu der secreten mangler for jobber som kjører mellom sletting og ny oppretting.

Grenser

OIDC som alternativ til secrets

For utrulling til skyleverandører (T Cloud Public, AWS, Azure, GCP) bør du vurdere OIDC-tokenføderasjon i stedet for langlivet legitimasjon lagret som secrets. OIDC utsteder kortlivede tokener per jobb, avgrenset til den bestemte workflow-kjøringen. Ingenting å rotere, ingenting å lekke.

OIDC er det anbefalte mønsteret for alle jobber som ruller ut til skyinfrastruktur.

Se også

• Actions og CI/CD: workflow-syntaks og permissions-blokken
• OIDC-tokenføderasjon: nøkkelfri skylegitimasjon
• Organisasjonsadministrasjon: administrasjon av secrets på organisasjonsnivå