Pakketregister

fremforge heeft een ingebouwd pakketregister. Pakketten staan binnen je organisatie. Er zijn geen langlevende registertokens: CI-jobs gebruiken het token dat elke Forgejo Actions-job al krijgt, en mensen gebruiken de fremforge-CLI, die elke tool een token geeft dat hooguit een uur geldig is.

Elk register wordt geleverd vanaf één host, frem.sh, onder een pad per organisatie en pakkettype:

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

Er zijn geen hostnamen per ecosysteem. Containerimages zijn de enige uitzondering op de padregel: die gebruiken de OCI-registry op frem.sh zelf.

Wil je publieke images en pakketten (Docker Hub, quay.io, npm, PyPI, Maven Central, NuGet, Go-modules, crates.io en meer) via je organisatie ophalen, met caching, verificatie, optionele malwarescan en je pakketbeleid toegepast, gebruik dan de dependency-proxy.

Ondersteunde pakkettypes

Paden in de tabel zijn relatief ten opzichte van https://frem.sh/api/packages/<org>/. Containerimages en Go-modules zijn de uitzonderingen en staan volledig uitgeschreven.

Elk type in de tabel staat aan voor elke organisatie. Voor Conda, CRAN, Conan, Chef, Pub, Swift, Vagrant, de Go-moduleproxy en generieke bestanden staat er nog geen recept op deze pagina: richt de client op het pad in de tabel en authenticeer zoals beschreven bij andere pakkettypes.

Bij een privé-organisatie geeft elk pad hierboven zonder token 401 terug, ook de index- en sleutelbestanden. Alleen de NuGet-serviceindex (nuget/index.json) is zonder token leesbaar, omdat de NuGet-client die ophaalt voordat hij authenticeert.

Authenticatie

Je kunt op drie manieren authenticeren:

Wie elk pakket mag lezen, publiceren en verwijderen, bepaalt de pakkettoegang van de organisatie, standaard voor de hele organisatie; eigenaren kunnen dat per pakket beperken en namen beschermen. Zie Pakkettoegang.

API-tokens (ffp_…) worden niet geaccepteerd door de registers. Die zijn alleen voor de REST-API van fremforge. Persoonlijke toegangstokens met pakketscopes worden niet uitgegeven: gebruik een registry-robot.

Publiceren vanuit Forgejo Actions

Het automatische token van elke job kan het register van de eigenaar van zijn repository gebruiken:

• Lezen: elk pakket van de eigenaar (de organisatie waartoe de repository hoort).
• Schrijven naar een pakket dat aan de eigen repository van de job is gekoppeld, of een nieuw pakket aanmaken. Een pakket dat een job aanmaakt, wordt automatisch aan de repository van die job gekoppeld.
• Pull requests vanuit forks krijgen alleen leestoegang, nooit schrijftoegang.

Je hoeft niets te declareren: er is geen permissions: packages: write om toe te voegen. Schrijven naar een pakket dat aan een andere repository is gekoppeld, of naar een pakket dat aan geen enkele repository is gekoppeld, wordt geweigerd met 403:

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

Voor een pakket met toegang per pakket kan een eigenaar ook de jobs van een andere repository lees- of schrijftoegang geven tot dat ene pakket (een Actions-toekenning); in een privé-organisatie kunnen jobs van repository’s zonder toekenning of koppeling het dan niet meer lezen.

Wil je een bestaand, niet-gekoppeld pakket vanuit een job publiceren, koppel het dan eerst aan de repository, op de pagina Instellingen van het pakket.

Het token werkt voor elke client als wachtwoord (met een willekeurige gebruikersnaam), en voor npm als Bearer-token. Eén workflow die elk gangbaar type publiceert:

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 leest het token uit de omgeving, dus je kunt het bestand committen:

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

Geef voor Gradle dezelfde waarden mee als properties, bijvoorbeeld -PfremforgeUsername="${{ github.actor }}" -PfremforgePassword="$TOKEN", en lees ze zoals getoond bij Gradle.

Op je eigen machine: fremforge auth

Installeer de fremforge-CLI en log in. Het inloggen verloopt via de single sign-on en MFA van je organisatie:

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

Inloggen met een apparaatcode vereist CLI 0.5.0 of nieuwer.

Stel daarna elke tool één keer in:

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

Wat configure per tool doet:

De helper en het keyring-commando zijn kleine scripts in ~/.local/bin (op Windows %LOCALAPPDATA%\fremforge\bin) die de CLI aanroepen. configure waarschuwt je als die map niet in je PATH staat.

Het token wordt automatisch vernieuwd. npm, Maven en Gradle kunnen niet zelf om een vers token vragen, dus de kopie in hun configuratie wordt herschreven telkens als je een fremforge-commando uitvoert, of expliciet met:

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

Voer het uit vóór een build, bijvoorbeeld als npm-preinstall-script ("preinstall": "fremforge auth refresh --quiet") of als pre-buildstap in je IDE.

Je login zelf (het refresh-token, 30 dagen geldig) wordt bewaard in de sleutelhanger van het besturingssysteem: macOS-sleutelhanger, Windows Credential Manager of de Secret Service op Linux. Is er geen sleutelhanger, of kan die niet worden gebruikt, dan valt de CLI terug op ~/.config/fremforge/auth.json met mode 600, en meldt dat. Ondersteuning voor de sleutelhanger op macOS en Windows is nieuw in 0.5.0 en is tot nu toe alleen met geautomatiseerde tests getest, niet op echte machines; de terugval op een bestand zorgt ervoor dat het blijft werken als een sleutelhanger weigert.

fremforge auth logout verwijdert de login en alle inloggegevens die configure heeft geschreven: de tokenregels voor npm, Maven en Gradle, de credHelpers-vermelding van docker, en de helper- en keyring-scripts. Het verwijdert alleen wat fremforge heeft geschreven, herkenbaar aan een commentaar fremforge-managed, dus je eigen regels blijven staan. Het kan het token niet op de server intrekken: een toegangstoken dat al is uitgegeven, blijft geldig tot het verloopt, hooguit 1 uur. Wil je de login direct beëindigen, verwijder dan fremforge-cli onder Geautoriseerde OAuth2 applicaties op frem.sh/user/settings/applications.

Andere pakkettypes

De CLI configureert docker, pip/uv, npm, Maven en Gradle. De andere clients op deze pagina (NuGet, Composer, RubyGems, Cargo, Helm, apt, dnf, apk, pacman en Go) hebben nog geen helper: publiceer die vanuit Forgejo Actions, waar <token> in de recepten hieronder ${{ secrets.FORGEJO_TOKEN }} is en <username> ${{ github.actor }}.

npm

Voeg een .npmrc-bestand toe aan de hoofdmap van je project:

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

fremforge auth configure npm levert het token (zie Authenticatie); voeg in Actions de _authToken-regel toe die in de workflow hierboven staat.

<scope> is de npm-scope van je pakket. Die hoeft niet overeen te komen met de naam van de organisatie: de organisatie acme kan bijvoorbeeld @acme-tools/*-pakketten publiceren.

Publiceren:

npm publish

Installeren:

npm install @<scope>/package-name

Docker / OCI

Voer op je eigen machine één keer fremforge auth configure docker uit; er is geen docker login. Log in Actions in met het job-token, zoals in de workflow hierboven.

Pushen en pullen:

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

OCI-artefacten met oras

Het register slaat ook OCI-artefacten op die geen containerimage zijn: SBOM’s, WASM-modules, beleidsbundels, handtekeningen en alles met een eigen artifactType. Gebruik oras 1.2 of nieuwer. Log in met een registry-robot of, in Actions, met het job-token:

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

Push een set bestanden onder één tag, met een eigen artefacttype en, optioneel, een eigen config-blob. Zonder --config schrijft oras de lege config (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

Koppel een artefact, zoals een SBOM, aan een bestaand image en bekijk wat eraan gekoppeld is:

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

Het gekoppelde manifest bevat een subject die naar het image verwijst. Het register heeft geen OCI 1.1- referrers-endpoint (/v2/<name>/referrers/<digest> geeft 404), net als ghcr.io: oras valt zelf terug op de referrers-tag sha256-<digest>, een index die bij elke attach wordt bijgewerkt. Elke tool die de tag-schema-terugval van OCI 1.1 volgt, zoals cosign, leest hem op dezelfde manier.

Groepeer artefacten in een index, en kopieer een tag met alles eronder:

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

Wat er voor een artefact geldt:

• Malwarescan. Elke geüploade blob wordt gescand, tar of niet. Een blob met een malware- signatuur wordt bij het uploaden geweigerd met DENIED, en een artefact kan pas worden gepulld als de blobs ervan zijn gescand. Zie Malwarescan.
• Beleid voor imagehandtekeningen. Een artefact is geen containerimage. Een manifest waarvan de config geen imageconfig is, of waarvan de lagen allemaal handtekeningen, attestaties of SBOM’s zijn, valt niet onder het beleid voor imagehandtekeningen van de organisatie, dus oras pull en cosign verify werken onder enforce. Hetzelfde geldt voor een index waarvan elke vermelding een artifactType declareert: een bundel van oras manifest index create, en de referrers-tag sha256-<digest> die oras discover leest, welke types er ook aan gekoppeld zijn. Een image waaraan een artefact is gekoppeld, valt zelf nog steeds onder het beleid, net als een image dat in zo’n index staat wanneer het op digest wordt gepulld.
• Kwetsbaarheidsscans. De dagelijkse Trivy-scan slaat artefacten over: hij scant alleen containerimages.
• Onveranderlijke tags. Onder het containertagbeleid van de organisatie (semver of all, zie Onveranderlijke releases) kan een bevroren tag niet naar een andere digest worden verplaatst of worden verwijderd, ook niet voor artefacten. oras push schrijft het huidige tijdstip in de annotatie org.opencontainers.image.created, dus dezelfde bestanden opnieuw pushen levert een nieuwe digest op, die een bevroren tag weigert. Wil je dat een herhaalde push idempotent is, leg dan de annotatie vast: --annotation org.opencontainers.image.created=<timestamp>. Koppelen aan een image achter een bevroren tag werkt: de koppeling wordt op digest gepusht, en de referrers-tag sha256-<digest> is geen versietag.
• Verwijderen. oras manifest delete frem.sh/<org>/<name>@<digest> vereist de eigen login van een beheerder van de organisatie. Registry-robots kunnen publiceren, maar niet verwijderen.
• Toegangslog en audit. Pushes, pulls, weigeringen en verwijderingen van artefacten worden vastgelegd in het toegangslog en het auditlog, net als bewerkingen op images.

Maven

Voeg de distributierepository toe aan pom.xml:

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

Wil je eruit installeren, voeg dan dezelfde URL toe onder <repositories> met dezelfde <id>.

De inloggegevens komen van fremforge auth configure maven, dat de serververmelding fremforge naar ~/.m2/settings.xml schrijft, of in Actions uit een settings-bestand dat het job-token leest (zie Publiceren vanuit Forgejo Actions).

Gradle

Declareer de repository en lees de inloggegevens uit de properties die fremforge auth configure gradle schrijft (of die je in Actions meegeeft met -P):

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

NuGet

Registreer de bron:

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

PyPI

Laat pip en uv op je eigen machine, na fremforge auth configure pip, keyring raadplegen. pip vereist de gebruikersnaam in de index-URL; gebruik je fremforge-gebruikersnaam:

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

Publiceer vanuit Actions met twine, zoals in de workflow hierboven:

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

Composer

Voeg de repository toe aan composer.json:

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

Voeg inloggegevens toe aan auth.json in de hoofdmap van je project:

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

Publiceer een pakketarchief. De queryparameter version is nodig, tenzij composer.json in het archief er een instelt:

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

RubyGems

Push een gem met een API-sleutel:

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

Cargo

Voeg het register toe aan .cargo/config.toml:

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

Voeg inloggegevens toe aan ~/.cargo/credentials.toml:

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

Publiceren:

cargo publish --registry fremforge

Go-modules

Go-modules worden rechtstreeks vanaf de URL van de repository geleverd:

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

Is je Go-module privé, markeer hem dan zo, zodat de Go-toolchain de publieke proxy en de checksumdatabase overslaat:

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

GOPRIVATE is de standaard omgevingsvariabele van Go hiervoor; die schakelt in één instelling de opvragingen bij GOPROXY en GOSUMDB uit voor overeenkomende paden. Om met go get te authenticeren heeft Git inloggegevens voor frem.sh nodig: in Actions het checkout-token, op je eigen machine je gewone Git-login.

Helm

Helm-charts kun je in twee vormen opslaan, en je kunt een van beide of allebei gebruiken:

• Als OCI-artefacten in de containerregistry op frem.sh, naast je images: oci://frem.sh/<org>/<chart>.
• In een klassieke chartrepository (index.yaml plus chartarchieven) op https://frem.sh/api/packages/<org>/helm.

Het zijn twee aparte opslagplaatsen. Een chart die als OCI is gepusht, verschijnt niet in de klassieke index.yaml, en andersom ook niet.

<username> en <token> zijn zoals beschreven bij Andere pakkettypes.

Helm-charts als OCI-artefacten

Vereist Helm 3.8 of nieuwer. Log één keer in en push daarna de verpakte chart naar de organisatie. De naam en versie van de chart worden de repository en de 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>

Installeer of pull rechtstreeks uit het register; voor OCI is er geen helm repo add:

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

De chart wordt opgeslagen als containerpakket met de naam <chart>, dus hij staat onder Pakketten van de organisatie bij je images, en een pull ervan gaat door dezelfde malwarescan-controle als een pull van een image.

Wil je een chartversie weghalen, verwijder die dan met de pakket-API, type container. Een push maakt ook een versie aan met de manifestdigest als naam (sha256:…); verwijder die ook, anders blijft de inhoud van de chart opgeslagen.

Klassieke Helm-chartrepository

Publiceer een verpakte chart:

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

Een geslaagde upload geeft 201 terug.

Een gepubliceerde chartversie kan niet worden overschreven. Upload je dezelfde versie opnieuw met andere inhoud, dan krijg je 409 met een melding die begint met immutable package: en zegt dat het bestand al is gepubliceerd; er wordt niets vervangen. Wil je een wijziging publiceren, verhoog dan version in Chart.yaml, verpak de chart opnieuw en upload de nieuwe versie. Upload je precies hetzelfde archief opnieuw, zoals een opnieuw gestarte CI-job doet, dan krijg je 201 en verandert er niets. Zie Onveranderlijke releases.

Voeg de repository toe en installeer eruit. Bij een privé-organisatie geeft de index zonder token 401 terug:

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

Verwijder een versie met de pakket-API, type helm. Het nummer van een verwijderde versie blijft buiten gebruik: upload je die versie opnieuw, met welke inhoud dan ook, dan krijg je 409.

Debian

De repository is ondertekend. De publieke sleutel staat op .../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

Geef apt bij een privé-organisatie het token in /etc/apt/auth.conf.d/fremforge.conf (machine frem.sh login <username> password <token>).

Publiceer een .deb in een distributie en component naar keuze:

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

Voeg de repository toe. Het .repo-bestand dat hij levert, laat gpgkey naar de ondertekeningssleutel wijzen, zodat dnf de pakketten verifieert:

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

Voeg bij een privé-organisatie username=<username> en password=<token> toe aan de sectie van de repository in /etc/yum.repos.d/.

Publiceren:

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

Installeer de ondertekeningssleutel en voeg daarna de repository toe. <branch> en <repository> zijn namen die je kiest bij het publiceren, bijvoorbeeld v3.20 en 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

Publiceren:

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

Arch

Importeer de ondertekeningssleutel en voeg daarna de repository toe aan /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

Publiceren:

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>

Scannen van containerimages

Elk containerimage in het register wordt dagelijks met Trivy gescand. De resultaten verschijnen onder Beveiliging › Bevindingen › Containerimages. Zie Scannen van containerimages voor wat er wordt gescand en hoe je pulls blokkeert, en Kwaadaardige pakketten voor de malwarecontrole op images.

Bewaren en opruimen

Pakketten worden standaard onbeperkt bewaard.

• Een versie verwijderen via de UI: detailpagina van het pakket → Delete version.
• Verwijderen via de API: DELETE https://frem.sh/api/v1/packages/<org>/<type>/<name>/<version>
• Opruimen in bulk: Organisatiebeheer → Pakketten → Opschoonregels; selecteer tags met een regex en bewaar de nieuwste N versies.

Opslagquotum

Wat de dependency-proxy cachet, telt mee voor dezelfde pakketpool, naast je eigen pakketten. Zie Opslaglimieten en quota.

Kruisverwijzingen

• Beveiliging en toeleveringsketen: configuratie van het scannen van containerimages
• CI-runners: pakketten publiceren vanuit workflowjobs
• Publieke REST-API: pakketten programmatisch beheren