Pakkeregister

fremforge har et innebygd pakkeregister. Pakkene ligger i organisasjonen din. Det finnes ingen langlivede registertokener: CI-jobber bruker tokenet som hver Forgejo Actions-jobb allerede får, og personer bruker fremforge-CLI-en, som gir hvert verktøy et token som varer høyst én time.

Alle registre leveres fra én vert, frem.sh, under en sti per organisasjon og pakketype:

https://frem.sh/api/packages/<org>/<type>/

Det finnes ingen vertsnavn per økosystem. Containerimager er det eneste unntaket fra sti-regelen: de bruker OCI-registeret på selve frem.sh.

For å pulle offentlige imager og pakker (Docker Hub, quay.io, npm, PyPI, Maven Central, NuGet, Go-moduler, crates.io med flere) gjennom organisasjonen din, med bufring, verifisering, valgfri skanning etter skadevare og pakkepolicyen din, bruker du avhengighetsproxyen.

Støttede pakketyper

Stiene i tabellen er relative til https://frem.sh/api/packages/<org>/. Containerimager og Go-moduler er unntakene og vises i sin helhet.

Alle typene i tabellen er slått på for alle organisasjoner. Conda, CRAN, Conan, Chef, Pub, Swift, Vagrant, Go-modulproxyen og generiske filer har ennå ingen oppskrift på denne siden: pek klienten til stien i tabellen og autentiser som beskrevet for andre pakketyper.

For en privat organisasjon svarer hver sti over 401 uten token, også indeks- og nøkkelfilene. Bare tjenesteindeksen for NuGet (nuget/index.json) kan leses uten, fordi NuGet-klienten henter den før den autentiserer seg.

Autentisering

Det finnes tre måter å autentisere på:

Hvem som kan lese, publisere og slette hver pakke, bestemmes av organisasjonens pakketilgang, som gjelder for hele organisasjonen som standard; eiere kan snevre den inn per pakke og beskytte navn. Se Pakketilgang.

API-tokener (ffp_…) godtas ikke av registrene. De er bare for fremforges REST-API. Personlige tilgangstokener med pakkescopes utstedes ikke: bruk en registerrobot.

Publisere fra Forgejo Actions

Det automatiske tokenet i hver jobb kan bruke registeret til eieren av repositoryet:

• Lese alle pakkene til eieren (organisasjonen repositoryet tilhører).
• Skrive til en pakke som er koblet til jobbens eget repository, eller opprette en ny pakke. En pakke som opprettes av en jobb, kobles automatisk til jobbens repository.
• Pull requests fra forks får bare lesetilgang, aldri skrivetilgang.

Ingenting må deklareres: det finnes ingen permissions: packages: write å legge til. En skriving til en pakke som er koblet til et annet repository, eller til en pakke som ikke er koblet til noe repository, avvises med 403:

forbidden: this job's token can only write packages linked to its own repository; npm package "@acme/ui" belongs to another repository

For en pakke med pakketilgang per pakke kan en eier også gi jobbene i et annet repository lese- eller skrivetilgang til akkurat den pakken (en Actions-tildeling); i en privat organisasjon kan jobber i repositoryer uten tildeling eller kobling da ikke lenger lese den.

For å publisere en eksisterende pakke som ikke er koblet, fra en jobb, kobler du den først til repositoryet på pakkens Innstillinger-side.

Tokenet virker som passord (med hvilket som helst brukernavn) for alle klienter, og som Bearer-token for npm. Én workflow som publiserer hver av de vanlige typene:

name: publish
on:
  push:
    tags: ['v*']

jobs:
  publish:
    runs-on: ubuntu-latest
    env:
      TOKEN: ${{ secrets.FORGEJO_TOKEN }}
      ORG: ${{ github.repository_owner }}
    steps:
      - uses: actions/checkout@v4

      - name: Container image
        run: |
          echo "$TOKEN" | docker login frem.sh -u "${{ github.actor }}" --password-stdin
          docker build -t "frem.sh/$ORG/app:${GITHUB_REF_NAME}" .
          docker push "frem.sh/$ORG/app:${GITHUB_REF_NAME}"

      - name: npm
        run: |
          printf '//frem.sh/api/packages/%s/npm/:_authToken=%s\n' "$ORG" "$TOKEN" >> "$HOME/.npmrc"
          npm publish

      - name: PyPI
        run: |
          python -m pip install build twine
          python -m build
          twine upload --repository-url "https://frem.sh/api/packages/$ORG/pypi" \
            -u "${{ github.actor }}" -p "$TOKEN" dist/*

      - name: Maven
        run: mvn --batch-mode deploy -s .ci/settings.xml
        env:
          FREMFORGE_USER: ${{ github.actor }}

.ci/settings.xml leser tokenet fra miljøet, så filen kan committes:

<settings>
  <servers>
    <server>
      <id>fremforge</id>
      <username>${env.FREMFORGE_USER}</username>
      <password>${env.TOKEN}</password>
    </server>
  </servers>
</settings>

For Gradle sender du de samme verdiene som properties, for eksempel -PfremforgeUsername="${{ github.actor }}" -PfremforgePassword="$TOKEN", og leser dem som vist under Gradle.

På maskinen din: fremforge auth

Installer fremforge-CLI-en og logg inn. Innloggingen går gjennom organisasjonens SSO og MFA:

fremforge auth login                 # opens a browser
fremforge auth login --device        # headless or SSH box: shows a code to approve in any
                                     # browser at https://frem.sh/_app/device

Innlogging med enhetskode krever CLI 0.5.0 eller nyere.

Sett deretter opp hvert verktøy én gang:

fremforge auth configure docker pip npm maven gradle
# or in one go:
fremforge auth login --configure=docker,pip,npm,maven,gradle

Dette gjør configure per verktøy:

Hjelperen og keyring-kommandoen er små skript i ~/.local/bin (på Windows %LOCALAPPDATA%\fremforge\bin) som kaller CLI-en. configure advarer deg når den mappen ikke er i PATH.

Tokenet fornyes automatisk. npm, Maven og Gradle har ingen måte å be om et nytt token på, så kopien i konfigurasjonen deres skrives på nytt hver gang du kjører en fremforge-kommando, eller eksplisitt med:

fremforge auth refresh     # makes sure the written token is valid for at least 30 more minutes

Kjør den før et bygg, for eksempel som et npm-preinstall-skript ("preinstall": "fremforge auth refresh --quiet") eller som et steg før bygg i IDE-en.

Selve innloggingen din (refresh-tokenet, gyldig i 30 dager) lagres i operativsystemets nøkkelring: macOS Keychain, Windows Credential Manager eller Secret Service på Linux. Der det ikke finnes noen nøkkelring, eller den ikke kan brukes, faller CLI-en tilbake til ~/.config/fremforge/auth.json med modus 600 og sier fra om det. Støtten for nøkkelring på macOS og Windows er ny i 0.5.0 og så langt bare testet med automatiske tester, ikke på ekte maskiner; reserveløsningen med fil er det som holder det i gang hvis en nøkkelring sier nei.

fremforge auth logout fjerner innloggingen og all legitimasjon som configure skrev: tokenlinjene for npm, Maven og Gradle, docker-oppføringen i credHelpers, og hjelpe- og keyring-skriptene. Den fjerner bare det fremforge skrev, gjenkjent på en fremforge-managed-kommentar, så dine egne linjer blir stående. Den kan ikke tilbakekalle tokenet på serveren: et tilgangstoken som allerede er utstedt, er gyldig til det utløper, høyst 1 time. For å avslutte innloggingen med en gang fjerner du fremforge-cli under Autoriserte OAuth2-applikasjoner på frem.sh/user/settings/applications.

Andre pakketyper

CLI-en setter opp docker, pip/uv, npm, Maven og Gradle. De andre klientene på denne siden (NuGet, Composer, RubyGems, Cargo, Helm, apt, dnf, apk, pacman og Go) har ennå ingen hjelper: publiser dem fra Forgejo Actions, der <token> i oppskriftene nedenfor er ${{ secrets.FORGEJO_TOKEN }} og <username> er ${{ github.actor }}.

npm

Legg til en .npmrc-fil i roten av prosjektet:

@<scope>:registry=https://frem.sh/api/packages/<org>/npm/

fremforge auth configure npm sørger for tokenet (se Autentisering); i Actions legger du til _authToken-linjen som vises i workflowen over.

<scope> er npm-scopet til pakken din. Det trenger ikke å stemme med organisasjonsnavnet: organisasjonen acme kan for eksempel publisere @acme-tools/*-pakker.

Publiser:

npm publish

Installer:

npm install @<scope>/package-name

Docker / OCI

På maskinen din kjører du fremforge auth configure docker én gang; det trengs ingen docker login. I Actions logger du inn med jobbtokenet som i workflowen over.

Push og pull:

docker push frem.sh/<org>/<image>:<tag>
docker pull frem.sh/<org>/<image>:<tag>

OCI-artefakter med oras

Registeret lagrer også OCI-artefakter som ikke er containerimager: SBOM-er, WASM-moduler, policypakker, signaturer og alt annet med sin egen artifactType. Bruk oras 1.2 eller nyere. Logg inn med en registerrobot eller, i Actions, med jobbtokenet:

echo "<token>" | oras login frem.sh -u <username> --password-stdin

Push et sett med filer under én tag, med en egen artefakttype og eventuelt en egen config-blob. Uten --config skriver oras den tomme konfigurasjonen (application/vnd.oci.empty.v1+json):

oras push frem.sh/<org>/<name>:1.0.0 \
  --artifact-type application/vnd.example.module.v1 \
  --config config.json:application/vnd.example.config.v1+json \
  module.wasm:application/vnd.wasm.content.layer.v1+wasm \
  sbom.spdx.json:application/spdx+json

oras pull frem.sh/<org>/<name>:1.0.0 -o ./out
oras manifest fetch frem.sh/<org>/<name>:1.0.0

Knytt en artefakt, for eksempel en SBOM, til et eksisterende image, og list det som er knyttet til:

oras attach frem.sh/<org>/<image>:<tag> --artifact-type application/spdx+json \
  sbom.spdx.json:application/spdx+json
oras discover frem.sh/<org>/<image>:<tag>
oras discover frem.sh/<org>/<image>:<tag> --artifact-type application/spdx+json

Det tilknyttede manifestet har et subject som peker på imaget. Registeret har ikke OCI 1.1-endepunktet for referrers (/v2/<name>/referrers/<digest> svarer 404), akkurat som ghcr.io: oras faller av seg selv tilbake til referrers-taggen sha256-<digest>, en indeks som holdes oppdatert ved hver tilknytning. Alle verktøy som følger OCI 1.1-reserveløsningen med tag-skjema, for eksempel cosign, leser den på samme måte.

Grupper artefakter i en indeks, og kopier en tag med alt under den:

oras manifest index create frem.sh/<org>/<name>:1.0.0-bundle 1.0.0 1.0.0-sbom
oras copy --recursive frem.sh/<org>/<name>:1.0.0-bundle --to-oci-layout ./layout:bundle

Dette gjelder for en artefakt:

• Skanning etter skadevare. Hver opplastet blob skannes, enten den er tar eller ikke. En blob med en skadevaresignatur avvises ved opplasting med DENIED, og en artefakt kan ikke pulles før blobene er skannet. Se Skanning etter skadevare.
• Signaturpolicy for imager. En artefakt er ikke et containerimage. Et manifest der konfigurasjonen ikke er en image-konfigurasjon, eller der alle lagene er signaturer, attesteringer eller SBOM-er, sperres ikke av organisasjonens signaturpolicy for imager, så oras pull og cosign verify virker under enforce. Det samme gjelder en indeks der hver oppføring deklarerer en artifactType: en pakke laget med oras manifest index create, og referrers-taggen sha256-<digest> som oras discover leser, uansett hvilke typer som er knyttet til. Et image med en artefakt knyttet til sperres fortsatt på selve imaget, og det samme gjelder et image som står i en slik indeks, når det pulles via digest.
• Sårbarhetsskanning. Den daglige Trivy-skanningen hopper over artefakter: den skanner bare containerimager.
• Uforanderlige tagger. Under organisasjonens policy for container-tagger (semver eller all, se Uforanderlige utgivelser) kan en frosset tag ikke flyttes til en annen digest eller slettes, heller ikke for artefakter. oras push skriver nåværende tidspunkt i annotasjonen org.opencontainers.image.created, så en ny push av de samme filene gir en ny digest, som en frosset tag avviser. For å gjøre en push idempotent ved ny kjøring låser du annotasjonen: --annotation org.opencontainers.image.created=<timestamp>. Å knytte noe til et image bak en frosset tag virker: tilknytningen pushes via digest, og referrers-taggen sha256-<digest> er ikke en versjonstag.
• Sletting. oras manifest delete frem.sh/<org>/<name>@<digest> krever en organisasjonsadministrators egen innlogging. Registerroboter kan publisere, men ikke slette.
• Tilgangslogg og revisjon. Push, pull, avvisninger og sletting av artefakter registreres i tilgangsloggen og revisjonsloggen, som for imager.

Maven

Legg til distribusjonsrepositoryet i pom.xml:

<distributionManagement>
  <repository>
    <id>fremforge</id>
    <url>https://frem.sh/api/packages/<org>/maven</url>
  </repository>
</distributionManagement>

For å installere fra det legger du til samme URL under <repositories> med samme <id>.

Legitimasjonen kommer fra fremforge auth configure maven, som skriver serveroppføringen fremforge til ~/.m2/settings.xml, eller i Actions fra en innstillingsfil som leser jobbtokenet (se Publisere fra Forgejo Actions).

Gradle

Deklarer repositoryet og les legitimasjonen fra propertiene som fremforge auth configure gradle skriver (eller som du sender med -P i Actions):

repositories {
    maven {
        url = uri("https://frem.sh/api/packages/<org>/maven")
        credentials {
            username = providers.gradleProperty("fremforgeUsername").get()
            password = providers.gradleProperty("fremforgePassword").get()
        }
    }
}

NuGet

Registrer kilden:

dotnet nuget add source https://frem.sh/api/packages/<org>/nuget/index.json \
  --name fremforge \
  --username <username> \
  --password <token>

PyPI

På maskinen din, etter fremforge auth configure pip, ber du pip og uv om å spørre keyring. Brukernavnet i indeks-URL-en kreves av pip; bruk fremforge-brukernavnet ditt:

pip config set global.keyring-provider subprocess
pip install --index-url https://<username>@frem.sh/api/packages/<org>/pypi/simple/ package-name

UV_KEYRING_PROVIDER=subprocess \
  uv pip install --index-url https://<username>@frem.sh/api/packages/<org>/pypi/simple/ package-name

Publiser fra Actions med twine, som i workflowen over:

twine upload --repository-url https://frem.sh/api/packages/<org>/pypi -u <username> -p <token> dist/*

Composer

Legg til repositoryet i composer.json:

{
  "repositories": [
    { "type": "composer", "url": "https://frem.sh/api/packages/<org>/composer" }
  ]
}

Legg til legitimasjon i auth.json i roten av prosjektet:

{
  "http-basic": {
    "frem.sh": {
      "username": "<username>",
      "password": "<token>"
    }
  }
}

Publiser et pakkearkiv. Spørreparameteren version trengs med mindre composer.json i arkivet setter en:

curl --user <username>:<token> -X PUT \
  --upload-file package.zip \
  "https://frem.sh/api/packages/<org>/composer?version=1.0.0"

RubyGems

Push en gem med en API-nøkkel:

gem push --key fremforge \
  --host https://frem.sh/api/packages/<org>/rubygems \
  your-gem-0.1.0.gem

Cargo

Legg til registeret i .cargo/config.toml:

[registries]
fremforge = { index = "sparse+https://frem.sh/api/packages/<org>/cargo/" }

Legg til legitimasjon i ~/.cargo/credentials.toml:

[registries.fremforge]
token = "Bearer <token>"

Publiser:

cargo publish --registry fremforge

Go-moduler

Go-moduler leveres direkte fra repository-URL-en:

go get frem.sh/<org>/<repo>@v1.2.3

Hvis Go-modulen din er privat, merker du den som det, slik at Go-verktøykjeden hopper over den offentlige proxyen og sjekksumdatabasen:

export GOPRIVATE=frem.sh/<org>/*

GOPRIVATE er den kanoniske Go-miljøvariabelen for dette; den slår av oppslag i GOPROXY og GOSUMDB for stier som samsvarer, med én innstilling. For at go get skal kunne autentisere, trenger Git en legitimasjon for frem.sh: i Actions checkout-tokenet, på maskinen din den vanlige Git-innloggingen.

Helm

Helm-charts kan lagres i to former, og du kan bruke den ene eller begge:

• Som OCI-artefakter i containerregisteret på frem.sh, ved siden av imagene dine: oci://frem.sh/<org>/<chart>.
• I et klassisk chart-repository (index.yaml pluss chart-arkiver) på https://frem.sh/api/packages/<org>/helm.

De to er atskilte lagre. Et chart som er pushet som OCI, vises ikke i den klassiske index.yaml, og omvendt.

<username> og <token> er som beskrevet under Andre pakketyper.

Helm-charts som OCI-artefakter

Krever Helm 3.8 eller nyere. Logg inn én gang, og push deretter det pakkede chartet til organisasjonen. Chartets navn og versjon blir repository og tag:

echo "<token>" | helm registry login frem.sh -u <username> --password-stdin
helm package ./<chart>                                    # writes <chart>-1.0.0.tgz
helm push <chart>-1.0.0.tgz oci://frem.sh/<org>

Installer eller pull direkte fra registeret; det finnes ingen helm repo add for OCI:

helm install my-release oci://frem.sh/<org>/<chart> --version 1.0.0
helm pull oci://frem.sh/<org>/<chart> --version 1.0.0

Chartet lagres som en containerpakke med navnet <chart>, så det listes under organisasjonens Pakker sammen med imagene dine, og en pull av det går gjennom den samme sperren for skanning etter skadevare som en pull av et image.

For å fjerne en chart-versjon sletter du den med pakke-API-et, type container. En push lager også en versjon som har navn etter manifestets digest (sha256:…); slett den også, ellers blir chartets innhold liggende lagret.

Klassisk Helm-chart-repository

Publiser et pakket chart:

curl --user <username>:<token> -X POST \
  --upload-file ./<chart>-1.0.0.tgz \
  https://frem.sh/api/packages/<org>/helm/api/charts

En vellykket opplasting svarer 201.

En publisert chart-versjon kan ikke overskrives. Hvis du laster opp samme versjon igjen med annet innhold, svarer registeret 409 med en melding som starter med immutable package: og sier at filen allerede er publisert; ingenting erstattes. For å publisere en endring øker du version i Chart.yaml, pakker chartet på nytt og laster opp den nye versjonen. Laster du opp det identiske arkivet igjen, slik en CI-jobb som kjøres på nytt gjør, svarer registeret 201 og endrer ingenting. Se Uforanderlige utgivelser.

Legg til repositoryet og installer fra det. For en privat organisasjon svarer indeksen 401 uten token:

echo "<token>" | helm repo add fremforge https://frem.sh/api/packages/<org>/helm \
  --username <username> --password-stdin
helm repo update
helm search repo fremforge/ --versions
helm install my-release fremforge/<chart> --version 1.0.0

Fjern en versjon med pakke-API-et, type helm. Versjonsnummeret til en slettet versjon forblir pensjonert: laster du opp den versjonen igjen, med hvilket som helst innhold, svarer registeret 409.

Debian

Repositoryet er signert. Den offentlige nøkkelen ligger på .../debian/repository.key:

sudo curl --user <username>:<token> \
  https://frem.sh/api/packages/<org>/debian/repository.key \
  -o /etc/apt/keyrings/fremforge-<org>.asc
echo "deb [signed-by=/etc/apt/keyrings/fremforge-<org>.asc] https://frem.sh/api/packages/<org>/debian <distribution> <component>" \
  | sudo tee /etc/apt/sources.list.d/fremforge.list

For en privat organisasjon gir du apt tokenet i /etc/apt/auth.conf.d/fremforge.conf (machine frem.sh login <username> password <token>).

Publiser en .deb i en distribusjon og komponent du velger selv:

curl --user <username>:<token> -X PUT \
  --upload-file package_1.0.0_amd64.deb \
  https://frem.sh/api/packages/<org>/debian/pool/<distribution>/<component>/upload

RPM

Legg til repositoryet. .repo-filen det leverer, peker gpgkey til signeringsnøkkelen, så dnf verifiserer pakkene:

sudo dnf config-manager --add-repo https://frem.sh/api/packages/<org>/rpm.repo

For en privat organisasjon legger du til username=<username> og password=<token> i repositoryets seksjon i /etc/yum.repos.d/.

Publiser:

curl --user <username>:<token> -X PUT \
  --upload-file package-1.0.0-1.x86_64.rpm \
  https://frem.sh/api/packages/<org>/rpm/upload

Alpine

Installer signeringsnøkkelen, og legg deretter til repositoryet. <branch> og <repository> er navn du velger når du publiserer, for eksempel v3.20 og main:

cd /etc/apk/keys && curl --user <username>:<token> -JO \
  https://frem.sh/api/packages/<org>/alpine/key
echo "https://<username>:<token>@frem.sh/api/packages/<org>/alpine/<branch>/<repository>" \
  >> /etc/apk/repositories

Publiser:

curl --user <username>:<token> -X PUT \
  --upload-file package-1.0.0-r0.apk \
  https://frem.sh/api/packages/<org>/alpine/<branch>/<repository>

Arch

Importer signeringsnøkkelen, og legg deretter til repositoryet i /etc/pacman.conf:

curl --user <username>:<token> -o fremforge.gpg \
  https://frem.sh/api/packages/<org>/arch/repository.key
sudo pacman-key --add fremforge.gpg
sudo pacman-key --lsign-key <key-id>

[<org>.frem.sh]
SigLevel = Required
Server = https://frem.sh/api/packages/<org>/arch/<repository>/$arch

Publiser:

curl --user <username>:<token> -X PUT \
  --upload-file package-1.0.0-1-x86_64.pkg.tar.zst \
  https://frem.sh/api/packages/<org>/arch/<repository>

Skanning av containerimager

Hvert containerimage i registeret skannes med Trivy i en daglig gjennomgang. Resultatene vises under Sikkerhet › Funn › Containerimager. Se Skanning av containerimager for hva som skannes og hvordan du blokkerer pulls, og Ondsinnede pakker for sjekken etter skadevare i imager.

Oppbevaring og opprydding

Pakker oppbevares på ubestemt tid som standard.

• Slett en versjon i webgrensesnittet: pakkens detaljside → Delete version.
• Slett via API: DELETE https://frem.sh/api/v1/packages/<org>/<type>/<name>/<version>
• Massesletting: Organisasjonsadministrasjon → Pakker → Oppryddingsregler, velg tagger med regex, behold de N nyeste versjonene.

Lagringskvote

Det avhengighetsproxyen bufrer, teller mot den samme pakkepotten, ved siden av dine egne pakker. Se Lagringsgrenser og kvoter.

Se også

• Sikkerhet og forsyningskjede: oppsett av skanning av containerimager
• CI-runnere: publisering av pakker fra workflow-jobber
• Offentlig REST-API: programmatisk administrasjon av pakker