Registre de paquets

fremforge comprend un registre de paquets intégré. Les paquets résident dans votre organisation. Il n’existe aucun jeton de registre à longue durée de vie : les tâches CI utilisent le jeton que chaque tâche Forgejo Actions reçoit déjà, et les personnes utilisent la CLI fremforge, qui fournit à chaque outil un jeton valable une heure au plus.

Tous les registres sont servis depuis un seul hôte, frem.sh, sous un chemin propre à chaque organisation et type de paquet :

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

Il n’y a pas de nom d’hôte par écosystème. Les images de conteneurs sont la seule exception à cette règle de chemin : elles utilisent le registre OCI de frem.sh lui-même.

Pour récupérer des images et des paquets publics (Docker Hub, quay.io, npm, PyPI, Maven Central, NuGet, modules Go, crates.io et d’autres) via votre organisation, avec mise en cache, vérification, analyse antimalware facultative et application de votre politique de paquets, utilisez le proxy de dépendances.

Types de paquets pris en charge

Les chemins du tableau sont relatifs à https://frem.sh/api/packages/<org>/. Les images de conteneurs et les modules Go font exception et sont indiqués en entier.

Chaque type du tableau est activé pour chaque organisation. Conda, CRAN, Conan, Chef, Pub, Swift, Vagrant, le proxy de modules Go et les fichiers génériques n’ont pas encore de recette sur cette page : faites pointer le client vers le chemin du tableau et authentifiez-vous comme indiqué pour les autres types de paquets.

Pour une organisation privée, chaque chemin ci-dessus répond 401 sans jeton, y compris les fichiers d’index et de clé. Seul l’index de service NuGet (nuget/index.json) est lisible sans jeton, car le client NuGet le récupère avant de s’authentifier.

Authentification

Il existe trois façons de s’authentifier :

Qui peut lire, publier et supprimer chaque paquet relève de l’accès aux paquets de l’organisation, valable pour toute l’organisation par défaut ; les propriétaires peuvent le restreindre paquet par paquet et protéger des noms. Voir Accès aux paquets.

Les jetons d’API (ffp_…) ne sont pas acceptés par les registres. Ils servent uniquement à l’API REST fremforge. Aucun jeton d’accès personnel avec des scopes de paquets n’est émis : utilisez un robot de registre.

Publier depuis Forgejo Actions

Le jeton automatique de chaque tâche peut utiliser le registre du propriétaire de son dépôt :

• Lire n’importe quel paquet du propriétaire (l’organisation à laquelle appartient le dépôt).
• Écrire dans un paquet lié au dépôt de la tâche elle-même, ou créer un nouveau paquet. Un paquet créé par une tâche est automatiquement lié au dépôt de cette tâche.
• Les pull requests provenant de forks obtiennent uniquement un accès en lecture, jamais en écriture.

Rien n’est à déclarer : il n’y a pas de permissions: packages: write à ajouter. Une écriture dans un paquet lié à un autre dépôt, ou dans un paquet qui n’est lié à aucun dépôt, est refusée avec 403 :

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

Pour un paquet en accès par paquet, un propriétaire peut aussi accorder aux tâches d’un autre dépôt la lecture ou l’écriture sur ce seul paquet (une autorisation Actions) ; dans une organisation privée, les tâches des dépôts qui n’ont ni autorisation ni lien ne peuvent alors plus le lire.

Pour publier depuis une tâche un paquet existant non lié, liez-le d’abord au dépôt, sur la page Paramètres du paquet.

Le jeton sert de mot de passe (avec n’importe quel nom d’utilisateur) pour tous les clients, et de jeton Bearer pour npm. Un workflow qui publie chacun des types courants :

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 lit le jeton dans l’environnement, il peut donc être commité :

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

Pour Gradle, passez les mêmes valeurs comme propriétés, par exemple -PfremforgeUsername="${{ github.actor }}" -PfremforgePassword="$TOKEN", et lisez-les comme indiqué dans Gradle.

Sur votre machine : fremforge auth

Installez la CLI fremforge et connectez-vous. La connexion passe par l’authentification unique (SSO) et la MFA de votre organisation :

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

La connexion par appareil nécessite la CLI 0.5.0 ou une version ultérieure.

Configurez ensuite chaque outil une fois :

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

Ce que fait configure pour chaque outil :

L’assistant et la commande keyring sont de petits scripts dans ~/.local/bin (sous Windows, %LOCALAPPDATA%\fremforge\bin) qui appellent la CLI. configure vous avertit lorsque ce répertoire n’est pas dans votre PATH.

Le jeton est renouvelé automatiquement. npm, Maven et Gradle n’ont aucun moyen de demander un jeton neuf : la copie présente dans leur configuration est donc réécrite chaque fois que vous exécutez une commande fremforge, ou explicitement avec :

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

Exécutez-la avant un build, par exemple comme script npm preinstall ("preinstall": "fremforge auth refresh --quiet") ou comme étape de pré-build de l’IDE.

Votre connexion elle-même (le jeton d’actualisation, valable 30 jours) est conservée dans le trousseau du système d’exploitation : Trousseau macOS, Gestionnaire d’identifiants Windows ou Secret Service sous Linux. Lorsqu’il n’y a pas de trousseau, ou qu’il ne peut pas être utilisé, elle se rabat sur ~/.config/fremforge/auth.json en mode 600, et la CLI l’indique. La prise en charge du trousseau sous macOS et Windows est nouvelle dans la version 0.5.0 et n’a jusqu’ici été testée que par des tests automatisés, pas sur de vraies machines ; c’est le repli sur fichier qui assure le fonctionnement si un trousseau refuse.

fremforge auth logout supprime la connexion et tous les identifiants que configure a écrits : les lignes de jeton npm, Maven et Gradle, l’entrée credHelpers de docker, ainsi que l’assistant et les scripts keyring. Elle ne supprime que ce que fremforge a écrit, reconnaissable à un commentaire fremforge-managed : vos propres lignes restent donc en place. Elle ne peut pas révoquer le jeton côté serveur : un jeton d’accès déjà émis reste valide jusqu’à son expiration, 1 heure au plus. Pour mettre fin immédiatement à la connexion, supprimez fremforge-cli sous Applications OAuth2 autorisées sur frem.sh/user/settings/applications.

Autres types de paquets

La CLI configure docker, pip/uv, npm, Maven et Gradle. Les autres clients de cette page (NuGet, Composer, RubyGems, Cargo, Helm, apt, dnf, apk, pacman et Go) n’ont pas encore d’assistant : publiez-les depuis Forgejo Actions, où <token> dans les recettes ci-dessous vaut ${{ secrets.FORGEJO_TOKEN }} et <username> vaut ${{ github.actor }}.

npm

Ajoutez un fichier .npmrc à la racine de votre projet :

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

fremforge auth configure npm fournit le jeton (voir Authentification) ; dans Actions, ajoutez la ligne _authToken présentée dans le workflow ci-dessus.

<scope> est le scope npm de votre paquet. Il n’a pas besoin de correspondre au nom de l’organisation : l’organisation acme, par exemple, peut publier des paquets @acme-tools/*.

Publier :

npm publish

Installer :

npm install @<scope>/package-name

Docker / OCI

Sur votre machine, exécutez une fois fremforge auth configure docker ; il n’y a pas de docker login. Dans Actions, connectez-vous avec le jeton de la tâche comme dans le workflow ci-dessus.

Push et pull :

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

Artefacts OCI avec oras

Le registre stocke aussi des artefacts OCI qui ne sont pas des images de conteneurs : SBOM, modules WASM, bundles de politiques, signatures et tout ce qui possède son propre artifactType. Utilisez oras 1.2 ou une version ultérieure. Connectez-vous avec un robot de registre ou, dans Actions, avec le jeton de la tâche :

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

Poussez un ensemble de fichiers sous un même tag, avec un type d’artefact personnalisé et, éventuellement, un blob de configuration de votre choix. Sans --config, oras écrit la configuration vide (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

Attachez un artefact, par exemple un SBOM, à une image existante, et listez ce qui y est attaché :

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

Le manifeste attaché porte un subject qui pointe vers l’image. Le registre n’a pas de point de terminaison referrers OCI 1.1 (/v2/<name>/referrers/<digest> répond 404), comme ghcr.io : oras se rabat de lui-même sur le tag referrers sha256-<digest>, un index qu’il tient à jour à chaque attachement. Tout outil qui suit le repli sur le schéma de tags OCI 1.1, comme cosign, le lit de la même façon.

Regroupez des artefacts dans un index, et copiez un tag avec tout ce qu’il contient :

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

Ce qui s’applique à un artefact :

• Analyse antimalware. Chaque blob envoyé est analysé, qu’il s’agisse d’un tar ou non. Un blob présentant une signature de logiciel malveillant est refusé à l’envoi avec DENIED, et un artefact ne peut pas être récupéré tant que ses blobs n’ont pas été analysés. Voir Analyse antimalware.
• Politique de signature des images. Un artefact n’est pas une image de conteneur. Un manifeste dont la configuration n’est pas une configuration d’image, ou dont toutes les couches sont des signatures, des attestations ou des SBOM, n’est pas soumis à la politique de signature des images de l’organisation : oras pull et cosign verify fonctionnent donc en mode enforce. Il en va de même pour un index dont chaque entrée déclare un artifactType : un bundle oras manifest index create, et le tag referrers sha256-<digest> que lit oras discover, quels que soient les types attachés. Une image à laquelle un artefact est attaché reste contrôlée sur l’image elle-même, de même qu’une image listée dans un tel index lorsqu’elle est récupérée par digest.
• Analyse des vulnérabilités. L’analyse Trivy quotidienne ignore les artefacts : elle n’analyse que les images de conteneurs.
• Tags immuables. Selon la politique de tags de conteneur de l’organisation (semver ou all, voir Releases immuables), un tag figé ne peut être ni déplacé vers un autre digest ni supprimé, artefacts compris. oras push écrit l’heure actuelle dans l’annotation org.opencontainers.image.created : pousser à nouveau les mêmes fichiers produit donc un nouveau digest, qu’un tag figé refuse. Pour rendre idempotent le push d’une nouvelle exécution, fixez l’annotation : --annotation org.opencontainers.image.created=<timestamp>. L’attachement à une image derrière un tag figé fonctionne : l’attachement est poussé par digest, et le tag referrers sha256-<digest> n’est pas un tag de version.
• Suppression. oras manifest delete frem.sh/<org>/<name>@<digest> nécessite la propre connexion d’un administrateur de l’organisation. Les robots de registre peuvent publier mais pas supprimer.
• Journal d’accès et audit. Les push, pull, refus et suppressions d’artefacts sont consignés dans le journal d’accès et dans le journal d’audit, comme les opérations sur les images.

Maven

Ajoutez le dépôt de distribution à pom.xml :

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

Pour installer depuis celui-ci, ajoutez la même URL sous <repositories> avec le même <id>.

Les identifiants proviennent de fremforge auth configure maven, qui écrit l’entrée de serveur fremforge dans ~/.m2/settings.xml, ou, dans Actions, d’un fichier de paramètres qui lit le jeton de la tâche (voir Publier depuis Forgejo Actions).

Gradle

Déclarez le dépôt et lisez les identifiants dans les propriétés qu’écrit fremforge auth configure gradle (ou que vous passez avec -P dans Actions) :

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

NuGet

Enregistrez la source :

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

PyPI

Sur votre machine, après fremforge auth configure pip, indiquez à pip et uv d’interroger keyring. Le nom d’utilisateur dans l’URL de l’index est exigé par pip ; utilisez votre nom d’utilisateur fremforge :

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

Publiez depuis Actions avec twine, comme dans le workflow ci-dessus :

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

Composer

Ajoutez le dépôt à composer.json :

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

Ajoutez les identifiants à auth.json à la racine de votre projet :

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

Publiez une archive de paquet. Le paramètre de requête version est nécessaire, sauf si le composer.json de l’archive en définit une :

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

RubyGems

Poussez une gem avec une clé d’API :

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

Cargo

Ajoutez le registre à .cargo/config.toml :

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

Ajoutez les identifiants à ~/.cargo/credentials.toml :

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

Publier :

cargo publish --registry fremforge

Modules Go

Les modules Go sont servis directement depuis l’URL du dépôt :

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

Si votre module Go est privé, marquez-le comme tel afin que la chaîne d’outils Go ignore le proxy public et la base de données de sommes de contrôle :

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

GOPRIVATE est la variable d’environnement Go prévue à cet effet ; elle désactive en un seul réglage les recherches GOPROXY et GOSUMDB pour les chemins correspondants. Pour que go get s’authentifie, Git a besoin d’un identifiant pour frem.sh : dans Actions, le jeton de checkout ; sur votre machine, votre connexion Git habituelle.

Helm

Les charts Helm peuvent être stockés sous deux formes, et vous pouvez utiliser l’une, l’autre ou les deux :

• Comme artefacts OCI dans le registre de conteneurs de frem.sh, à côté de vos images : oci://frem.sh/<org>/<chart>.
• Dans un dépôt de charts classique (index.yaml plus les archives des charts) à https://frem.sh/api/packages/<org>/helm.

Les deux sont des stockages distincts. Un chart poussé en OCI n’apparaît pas dans l’index.yaml classique, et inversement.

<username> et <token> sont tels que décrits dans Autres types de paquets.

Charts Helm comme artefacts OCI

Nécessite Helm 3.8 ou une version ultérieure. Connectez-vous une fois, puis poussez le chart empaqueté vers l’organisation. Le nom et la version du chart deviennent le dépôt et le 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>

Installez ou récupérez directement depuis le registre ; il n’y a pas de helm repo add pour 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

Le chart est stocké comme paquet de conteneur nommé <chart> : il est donc listé sous Packages de l’organisation avec vos images, et sa récupération passe par le même contrôle d’analyse antimalware qu’un pull d’image.

Pour supprimer une version de chart, supprimez-la avec l’API des paquets, type container. Un push crée aussi une version nommée d’après le digest du manifeste (sha256:…) ; supprimez-la également, sinon le contenu du chart reste stocké.

Dépôt de charts Helm classique

Publiez un chart empaqueté :

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

Un envoi réussi répond 201.

Une version de chart publiée ne peut pas être écrasée. Envoyer de nouveau la même version avec un contenu différent répond 409 avec un message qui commence par immutable package: et indique que le fichier est déjà publié ; rien n’est remplacé. Pour publier une modification, augmentez version dans Chart.yaml, empaquetez à nouveau le chart et envoyez la nouvelle version. Envoyer de nouveau l’archive identique, comme le fait une tâche CI relancée, répond 201 et ne change rien. Voir Releases immuables.

Ajoutez le dépôt et installez depuis celui-ci. Pour une organisation privée, l’index répond 401 sans jeton :

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

Supprimez une version avec l’API des paquets, type helm. Le numéro d’une version supprimée reste retiré : envoyer de nouveau cette version, quel que soit son contenu, répond 409.

Debian

Le dépôt est signé. Sa clé publique se trouve à .../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

Pour une organisation privée, fournissez le jeton à apt dans /etc/apt/auth.conf.d/fremforge.conf (machine frem.sh login <username> password <token>).

Publiez un .deb dans la distribution et le composant de votre choix :

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

Ajoutez le dépôt. Le fichier .repo qu’il sert fait pointer gpgkey vers la clé de signature, de sorte que dnf vérifie les paquets :

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

Pour une organisation privée, ajoutez username=<username> et password=<token> à la section du dépôt dans /etc/yum.repos.d/.

Publier :

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

Installez la clé de signature, puis ajoutez le dépôt. <branch> et <repository> sont des noms que vous choisissez lors de la publication, par exemple v3.20 et 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

Publier :

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

Arch

Importez la clé de signature, puis ajoutez le dépôt à /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

Publier :

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>

Analyse des images de conteneurs

Chaque image de conteneur du registre est analysée par Trivy lors d’un passage quotidien. Les résultats apparaissent dans Sécurité › Résultats › Images de conteneurs. Voir Analyse des images de conteneurs pour ce qui est analysé et comment bloquer les pulls, et Paquets malveillants pour la détection de logiciels malveillants dans les images.

Rétention et nettoyage

Par défaut, les paquets sont conservés indéfiniment.

• Supprimer une version dans l’interface : page de détail du paquet → Delete version.
• Supprimer via l’API : DELETE https://frem.sh/api/v1/packages/<org>/<type>/<name>/<version>
• Nettoyage en masse : Administration de l’organisation → Paquets → Cleanup policies, sélection des tags par expression régulière, conservation des N dernières versions.

Quota de stockage

Ce que le proxy de dépendances met en cache compte dans cette même réserve de paquets, à côté de vos propres paquets. Voir Limites et quotas de stockage.

Références croisées

• Sécurité et chaîne d’approvisionnement, configuration de l’analyse des images de conteneurs
• Runners CI, publication de paquets depuis les tâches de workflow
• API REST publique, gestion programmatique des paquets