Gå til hovedindhold

Brug fremforges registries fra GitHub Actions og OpenShift

Din kildekode og CI kan blive på GitHub og dine clusters på OpenShift, mens pakkerne ligger i din fremforge-organisation. Begge når registryet gennem en registry robot: et login, der tilhører organisationen og ikke en person.

En registry robot:

  • læser, eller læser og udgiver, pakkerne i én organisation, af alle pakketyper;
  • kan udgive, men ikke slette: sletning af en pakkeversion, en fil, et container-tag eller et image afvises med 403 og står i revisionsloggen som registry_robot.delete_refused. Sletning er forbeholdt en organisationsadministrator, i webbrugerfladen eller med eget login;
  • kan ikke læse kode, åbne webbrugerfladen eller nå nogen anden organisation;
  • tæller ikke som betalende bruger;
  • udløber senest efter 365 dage, hvorefter den og alle dens tokens holder op med at virke;
  • står, sammen med hvem der har oprettet den, under Administration → Sikkerhed → Adgang → Registry-robotter, og hver oprettelse, rotation, sletning og afvist pakkesletning står i organisationens revisionslog.

I fremforges egen CI har du ikke brug for en: et Forgejo Actions-job har allerede et token til sin egen organisations pakker. Se Udgivelse fra Forgejo Actions.

Opret en robot

I konsollen: Administration → Sikkerhed → Adgang → Registry-robotter → Opret en robot. Vælg Læse pakker til et pull secret og Læse og udgive pakker (kan ikke slette) til et CI-job, der udgiver.

Siden viser derefter robottens brugernavn og token én gang. Kopiér begge; tokenet vises ikke igen. Mister du det, udsteder Rotér token et nyt og tilbagekalder det gamle med det samme.

Eller med API’et, med et API-token, der har scopet policy:write:

curl -sS -X POST "https://frem.sh/_app/api/v1/orgs/<org>/registry-robots" \
  -H "Authorization: Bearer $FREMFORGE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "github-publish", "access": "write", "expires_in_days": 90}'

Svaret indeholder username og token. access er read eller write, og expires_in_days er 1 til 365 (standard 90). Rotér med POST /orgs/<org>/registry-robots/<id>/rotate, eventuelt med {"expires_in_days": n} for at sætte en ny udløbsdato, og slet med DELETE /orgs/<org>/registry-robots/<id>.

Brugernavnet har formen <org prefix>-fremforge-bot-reg-<8 hex characters>. Præfikset er organisationens navn, forkortet når det er nødvendigt, så brugernavnet holder sig inden for 40 tegn: en robot i acme-infrastructure-team hedder fx acme-infrastr-fremforge-bot-reg-1a2b3c4d. Kopiér brugernavnet fra siden eller API’et i stedet for at bygge det ud fra organisationens navn. Alle klienterne nedenfor tager det som brugernavn og tokenet som adgangskode.

GitHub Actions

Gem robotten i GitHub-repositoryet eller -organisationen: brugernavnet som variablen FREMFORGE_REGISTRY_USER og tokenet som secret’en FREMFORGE_REGISTRY_TOKEN. Sæt ORG til din fremforge-organisation.

Container-images

- name: Push to fremforge
  env:
    FREMFORGE_USER: ${{ vars.FREMFORGE_REGISTRY_USER }}
    FREMFORGE_TOKEN: ${{ secrets.FREMFORGE_REGISTRY_TOKEN }}
    ORG: <org>
  run: |
    echo "$FREMFORGE_TOKEN" | docker login frem.sh -u "$FREMFORGE_USER" --password-stdin
    docker build -t "frem.sh/$ORG/app:$GITHUB_SHA" .
    docker push "frem.sh/$ORG/app:$GITHUB_SHA"

Pull på samme måde, med docker pull frem.sh/<org>/app:<tag>. Et pushet tag kan ikke overskrives, når uforanderlige releases er slået til for organisationen.

npm

npm sender kun et token til en registry-URL, der matcher præcist, så giv den scopets registry og tokenet til netop den URL:

- name: Publish to fremforge
  env:
    FREMFORGE_TOKEN: ${{ secrets.FREMFORGE_REGISTRY_TOKEN }}
    ORG: <org>
  run: |
    printf '@<scope>:registry=https://frem.sh/api/packages/%s/npm/\n//frem.sh/api/packages/%s/npm/:_authToken=%s\n' \
      "$ORG" "$ORG" "$FREMFORGE_TOKEN" > .npmrc
    npm publish

Den samme .npmrc installerer @<scope>/…-pakker med npm install.

PyPI

- name: Publish to fremforge
  env:
    FREMFORGE_USER: ${{ vars.FREMFORGE_REGISTRY_USER }}
    FREMFORGE_TOKEN: ${{ secrets.FREMFORGE_REGISTRY_TOKEN }}
    ORG: <org>
  run: |
    python -m pip install twine
    twine upload --repository-url "https://frem.sh/api/packages/$ORG/pypi" \
      -u "$FREMFORGE_USER" -p "$FREMFORGE_TOKEN" dist/*

Installér med robottens legitimation i indeks-URL’en:

pip install --index-url "https://$FREMFORGE_USER:$FREMFORGE_TOKEN@frem.sh/api/packages/$ORG/pypi/simple/" <package>

Maven

Tilføj en server med det id, din pom.xml bruger til fremforge-repositoryet, og læs robotten fra miljøet:

<settings>
  <servers>
    <server>
      <id>fremforge</id>
      <username>${env.FREMFORGE_USER}</username>
      <password>${env.FREMFORGE_TOKEN}</password>
    </server>
  </servers>
</settings>
- name: Publish to fremforge
  env:
    FREMFORGE_USER: ${{ vars.FREMFORGE_REGISTRY_USER }}
    FREMFORGE_TOKEN: ${{ secrets.FREMFORGE_REGISTRY_TOKEN }}
  run: mvn --batch-mode -s .ci/settings.xml deploy

med repositoryet i pom.xml som under Maven: https://frem.sh/api/packages/<org>/maven.

Uden et gemt secret: GitHubs OIDC-token

En robot kan også acceptere GitHub Actions’ eget OIDC-token i stedet for et gemt registry-token. Giv robotten din GitHub-organisations (eller -brugers) numeriske id og eventuelt ét repository under GitHub Actions på robotten, eller med github_repository_owner_id og github_repository i API’et. Et job hos den ejer beder derefter om sit OIDC-token med audience https://frem.sh/<org> (permissions: id-token: write) og veksler det på POST https://frem.sh/_app/api/v1/registry/oidc-token (org, robot, id_token) til robottens brugernavn og et token, der gælder i 1 time. Vekslingen er beskrevet i API-referencen under Registry robots; hvert token, den udsteder, står i revisionsloggen med repository, ref og run-id.

SBOM’er

SBOM’er sendes til fremforges API, ikke til registryet, med et API-token, der har scopet sboms:write. Se Upload SBOM’er fra GitHub Actions.

OpenShift og Kubernetes

Hent images fra fremforge med en robot med læseadgang som image pull secret:

kubectl create secret docker-registry frem-sh \
  --docker-server=frem.sh \
  --docker-username=<robot username> \
  --docker-password=<robot token> \
  --namespace=<namespace>

og henvis til det fra workloaden:

spec:
  imagePullSecrets:
    - name: frem-sh
  containers:
    - name: app
      image: frem.sh/<org>/app:1.4.2

OpenShift læser det samme kubernetes.io/dockerconfigjson-secret. Rotér robotten, før den udløber, og erstat secret’et med et nyt, lavet ud fra det nye token.

Hosts, der skal åbnes i en egress-firewall

HostPortBruges til
frem.sh443Alle registry-forespørgsler: logins, indekser, uploads samt manifester og lag til container-images
obs.eu-de.otc.t-systems.com443Download af andre pakkefiler end container-images: npm-tarballs, wheels, JAR-filer og så videre

En download af en anden pakkefil end et container-image svarer 303 med et kortlivet signeret link til filen i object storage på obs.eu-de.otc.t-systems.com, som klienten følger. Det navn er et CNAME for obs.lz01.eu-de.otc.t-systems.com, så en firewall, der tjekker hvert navn i kæden, skal have begge. Lagene i container-images serveres af frem.sh selv.

frem.sh serveres gennem et CDN, så adresserne skifter: tillad den ved navn, ikke ved IP-adresse.

Afhængighedsproxy

En robot med læseadgang kan også hente gennem organisationens afhængighedsproxy (Docker Hub, npm, PyPI og de øvrige offentlige registries) med det samme token. Se Godkendelse.