Paketregister

fremforge har ett inbyggt paketregister. Paketen ligger i din organisation. Det finns inga långlivade registertokens: CI-jobb använder den token som varje jobb i Forgejo Actions redan får, och personer använder fremforge CLI, som ger varje verktyg en token som gäller i högst en timme.

Alla register levereras från en och samma värd, frem.sh, under en sökväg per organisation och pakettyp:

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

Det finns inga värdnamn per ekosystem. Container-images är det enda undantaget från sökvägsregeln: de använder OCI-registret direkt på frem.sh.

För att hämta publika images och paket (Docker Hub, quay.io, npm, PyPI, Maven Central, NuGet, Go-moduler, crates.io med flera) via din organisation, med cachning, verifiering, valfri skanning efter skadlig kod och din paketpolicy tillämpad, använder du beroendeproxyn.

Pakettyper som stöds

Sökvägarna i tabellen är relativa till https://frem.sh/api/packages/<org>/. Container-images och Go-moduler är undantagen och visas i sin helhet.

Alla typer i tabellen är aktiverade för alla organisationer. Conda, CRAN, Conan, Chef, Pub, Swift, Vagrant, Go-modulproxyn och generiska filer har ännu inget recept på den här sidan: peka klienten mot sökvägen i tabellen och autentisera som beskrivs för andra pakettyper.

För en privat organisation svarar varje sökväg ovan 401 utan token, även index- och nyckelfilerna. Bara NuGets tjänsteindex (nuget/index.json) kan läsas utan token, eftersom NuGet-klienten hämtar det innan den autentiserar.

Autentisering

Det finns tre sätt att autentisera:

Vem som får läsa, publicera och ta bort varje paket avgörs av organisationens paketåtkomst, som gäller hela organisationen som standard; ägare kan snäva in den per paket och skydda namn. Se Paketåtkomst.

API-tokens (ffp_…) godtas inte av registren. De är bara till för fremforges REST API. Personliga åtkomsttokens med paket-scopes utfärdas inte: använd en registerrobot.

Publicera från Forgejo Actions

Varje jobbs automatiska token kan använda registret hos ägaren av jobbets repository:

• Läsa vilket paket som helst hos ägaren (den organisation som repositoryt tillhör).
• Skriva ett paket som är länkat till jobbets eget repository, eller skapa ett nytt paket. Ett paket som skapas av ett jobb länkas automatiskt till jobbets repository.
• Pull requests från forkar får bara läsbehörighet, aldrig skrivbehörighet.

Ingenting behöver deklareras: det finns inget permissions: packages: write att lägga till. En skrivning till ett paket som är länkat till ett annat repository, eller till ett paket som inte är länkat till något repository, nekas med 403:

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

För ett paket med åtkomst per paket kan en ägare också ge ett annat repositorys jobb läs- eller skrivbehörighet till just det paketet (en Actions-behörighet); i en privat organisation kan jobb i repositoryn utan behörighet eller länk då inte längre läsa det.

För att publicera ett befintligt olänkat paket från ett jobb länkar du det först till repositoryt, på paketets sida Settings.

Token fungerar som lösenord (med vilket användarnamn som helst) för alla klienter, och som Bearer-token för npm. Ett workflow som publicerar varje vanlig typ:

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 läser token från miljön, så den kan committas:

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

För Gradle skickar du samma värden som properties, till exempel -PfremforgeUsername="${{ github.actor }}" -PfremforgePassword="$TOKEN", och läser dem som visas under Gradle.

På din dator: fremforge auth

Installera fremforge CLI och logga in. Inloggningen går via organisationens single sign-on och 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

Inloggning med enhetskod kräver CLI 0.5.0 eller senare.

Konfigurera sedan varje verktyg en gång:

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

Vad configure gör per verktyg:

Hjälpprogrammet och keyring-kommandot är små skript i ~/.local/bin (på Windows %LOCALAPPDATA%\fremforge\bin) som anropar CLI:t. configure varnar dig när den katalogen inte finns i din PATH.

Token förnyas automatiskt. npm, Maven och Gradle har inget sätt att be om en färsk token, så kopian i deras konfiguration skrivs om varje gång du kör något fremforge-kommando, eller uttryckligen med:

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

Kör det före ett bygge, till exempel som ett preinstall-skript i npm ("preinstall": "fremforge auth refresh --quiet") eller som ett förbyggsteg i IDE:n.

Själva inloggningen (refresh-token, giltig i 30 dagar) sparas i operativsystemets nyckelring: macOS Keychain, Windows Credential Manager eller Secret Service på Linux. Där det inte finns någon nyckelring, eller den inte kan användas, faller den tillbaka på ~/.config/fremforge/auth.json med läge 600, och CLI:t säger det. Stödet för nyckelringen på macOS och Windows är nytt i 0.5.0 och hittills bara testat av automatiska tester, inte på riktiga datorer; reservfilen är det som gör att det fortsätter fungera om en nyckelring vägrar.

fremforge auth logout tar bort inloggningen och varje inloggningsuppgift som configure skrev: npm-, Maven- och Gradle-raderna med token, docker-posten i credHelpers, samt hjälpprogrammet och keyring-skripten. Det tar bara bort det som fremforge skrev, som känns igen på en fremforge-managed-kommentar, så dina egna rader finns kvar. Det kan inte återkalla token på servern: en åtkomsttoken som redan har utfärdats förblir giltig tills den går ut, högst 1 timme. För att avsluta inloggningen direkt tar du bort fremforge-cli under Auktoriserade OAuth2-appar på frem.sh/user/settings/applications.

Andra pakettyper

CLI:t konfigurerar docker, pip/uv, npm, Maven och Gradle. De andra klienterna på den här sidan (NuGet, Composer, RubyGems, Cargo, Helm, apt, dnf, apk, pacman och Go) har ännu inget hjälpprogram: publicera dem från Forgejo Actions, där <token> i recepten nedan är ${{ secrets.FORGEJO_TOKEN }} och <username> är ${{ github.actor }}.

npm

Lägg till en .npmrc-fil i projektets rot:

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

fremforge auth configure npm tillhandahåller token (se Autentisering); i Actions lägger du till raden _authToken som visas i workflowet ovan.

<scope> är paketets npm-scope. Det behöver inte matcha organisationens namn: organisationen acme kan till exempel publicera paket under @acme-tools/*.

Publicera:

npm publish

Installera:

npm install @<scope>/package-name

Docker / OCI

På din dator kör du fremforge auth configure docker en gång; det behövs ingen docker login. I Actions loggar du in med jobbets token som i workflowet ovan.

Push och pull:

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

OCI-artefakter med oras

Registret lagrar också OCI-artefakter som inte är container-images: SBOM:er, WASM-moduler, policypaket, signaturer och allt annat med en egen artifactType. Använd oras 1.2 eller senare. Logga in med en registerrobot eller, i Actions, med jobbets token:

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

Pusha en uppsättning filer under en tagg, med en egen artefakttyp och, om du vill, en egen config-blob. Utan --config skriver oras den tomma configen (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

Bifoga en artefakt till en befintlig image, till exempel en SBOM, och lista det som är bifogat:

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 bifogade manifestet har ett subject som pekar på imagen. Registret har ingen OCI 1.1-endpoint för referrers (/v2/<name>/referrers/<digest> svarar 404), precis som ghcr.io: oras faller själv tillbaka på referrers-taggen sha256-<digest>, ett index som hålls uppdaterat vid varje attach. Alla verktyg som följer OCI 1.1:s reservlösning med taggschema, till exempel cosign, läser det på samma sätt.

Gruppera artefakter i ett index, och kopiera en tagg med allt 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

Det här gäller för en artefakt:

• Skanning efter skadlig kod. Varje uppladdad blob skannas, tar-arkiv eller inte. En blob med en signatur för skadlig kod nekas vid uppladdningen med DENIED, och en artefakt kan inte hämtas förrän dess blobbar är skannade. Se Skanning efter skadlig kod.
• Policy för image-signaturer. En artefakt är inte en container-image. Ett manifest vars config inte är en image-config, eller vars lager alla är signaturer, attesteringar eller SBOM:er, spärras inte av organisationens policy för image-signaturer, så oras pull och cosign verify fungerar under enforce. Detsamma gäller ett index där varje post deklarerar en artifactType: ett paket från oras manifest index create, och referrers-taggen sha256-<digest> som oras discover läser, oavsett vilka typer som är bifogade. En image med en bifogad artefakt spärras fortfarande för själva imagen, och det gör även en image som listas i ett sådant index när den hämtas via digest.
• Sårbarhetsskanning. Den dagliga Trivy-skanningen hoppar över artefakter: den skannar bara container-images.
• Oföränderliga taggar. Under organisationens policy för container-taggar (semver eller all, se Oföränderliga releaser) kan en fryst tagg inte flyttas till en annan digest eller tas bort, artefakter inräknade. oras push skriver aktuell tid i annotationen org.opencontainers.image.created, så att pusha samma filer igen ger en ny digest, vilket en fryst tagg nekar. För att göra en push idempotent vid omkörning låser du annotationen: --annotation org.opencontainers.image.created=<timestamp>. Att bifoga till en image bakom en fryst tagg fungerar: bilagan pushas via digest, och referrers-taggen sha256-<digest> är ingen versionstagg.
• Borttagning. oras manifest delete frem.sh/<org>/<name>@<digest> kräver en organisationsadministratörs egen inloggning. Registerrobotar kan publicera men inte ta bort.
• Åtkomstlogg och granskning. Push, pull, nekanden och borttagningar av artefakter registreras i åtkomstloggen och granskningsloggen, precis som image-operationer.

Maven

Lägg till distributionsrepositoryt i pom.xml:

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

För att installera därifrån lägger du till samma URL under <repositories> med samma <id>.

Inloggningsuppgifterna kommer från fremforge auth configure maven, som skriver serverposten fremforge till ~/.m2/settings.xml, eller i Actions från en inställningsfil som läser jobbets token (se Publicera från Forgejo Actions).

Gradle

Deklarera repositoryt och läs inloggningsuppgifterna från de properties som fremforge auth configure gradle skriver (eller som du skickar 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

Registrera källan:

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

PyPI

På din dator, efter fremforge auth configure pip, säger du åt pip och uv att fråga keyring. Användarnamnet i index-URL:en krävs av pip; använd ditt användarnamn i 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

Publicera från Actions med twine, som i workflowet ovan:

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

Composer

Lägg till repositoryt i composer.json:

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

Lägg till inloggningsuppgifter i auth.json i projektets rot:

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

Publicera ett paketarkiv. Frågeparametern version behövs om inte composer.json i arkivet anger en:

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

RubyGems

Pusha en gem med en API-nyckel:

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

Cargo

Lägg till registret i .cargo/config.toml:

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

Lägg till inloggningsuppgifter i ~/.cargo/credentials.toml:

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

Publicera:

cargo publish --registry fremforge

Go-moduler

Go-moduler levereras direkt från repositoryts URL:

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

Om din Go-modul är privat markerar du den som det, så att Go-verktygen hoppar över den publika proxyn och kontrollsummedatabasen:

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

GOPRIVATE är den kanoniska miljövariabeln i Go för detta; den stänger av uppslag mot GOPROXY och GOSUMDB för matchande sökvägar med en enda inställning. För att go get ska kunna autentisera behöver Git en inloggningsuppgift för frem.sh: i Actions checkout-token, på din dator din vanliga Git-inloggning.

Helm

Helm-chart kan lagras i två former, och du kan använda den ena eller båda:

• Som OCI-artefakter i container-registret på frem.sh, bredvid dina images: oci://frem.sh/<org>/<chart>.
• I ett klassiskt diagramrepository (index.yaml plus diagramarkiv) på https://frem.sh/api/packages/<org>/helm.

De två är separata lager. Ett diagram som pushas som OCI syns inte i det klassiska index.yaml, och tvärtom.

<username> och <token> är som beskrivs under Andra pakettyper.

Helm-chart som OCI-artefakter

Kräver Helm 3.8 eller senare. Logga in en gång och pusha sedan det paketerade diagrammet till organisationen. Diagrammets namn och version blir repository och tagg:

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>

Installera eller hämta direkt från registret; det finns ingen helm repo add för 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

Diagrammet lagras som ett containerpaket med namnet <chart>, så det listas under organisationens Packages tillsammans med dina images, och en hämtning av det passerar samma spärr för skanning efter skadlig kod som en image-hämtning.

För att ta bort en diagramversion tar du bort den med paket-API:t, typ container. En push skapar också en version som heter som manifestets digest (sha256:…); ta bort den också, annars ligger diagrammets innehåll kvar i lagringen.

Klassiskt repository för Helm-chart

Publicera ett paketerat diagram:

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

En lyckad uppladdning besvaras med 201.

En publicerad diagramversion kan inte skrivas över. Om du laddar upp samma version igen med annat innehåll svarar registret 409 med ett meddelande som börjar med immutable package: och säger att filen redan är publicerad; ingenting ersätts. För att publicera en ändring höjer du version i Chart.yaml, paketerar diagrammet igen och laddar upp den nya versionen. Att ladda upp exakt samma arkiv igen, som ett omkört CI-jobb gör, besvaras med 201 och ändrar ingenting. Se Oföränderliga releaser.

Lägg till repositoryt och installera därifrån. För en privat organisation svarar indexet 401 utan 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

Ta bort en version med paket-API:t, typ helm. En borttagen versions nummer förblir pensionerat: att ladda upp den versionen igen, med vilket innehåll som helst, besvaras med 409.

Debian

Repositoryt är signerat. Dess publika nyckel finns 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

För en privat organisation ger du apt token i /etc/apt/auth.conf.d/fremforge.conf (machine frem.sh login <username> password <token>).

Publicera en .deb i en distribution och komponent som du väljer:

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

Lägg till repositoryt. .repo-filen som det levererar pekar gpgkey mot signeringsnyckeln, så att dnf verifierar paketen:

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

För en privat organisation lägger du till username=<username> och password=<token> i repositoryts sektion i /etc/yum.repos.d/.

Publicera:

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

Installera signeringsnyckeln och lägg sedan till repositoryt. <branch> och <repository> är namn som du väljer när du publicerar, till exempel v3.20 och 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

Publicera:

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

Arch

Importera signeringsnyckeln och lägg sedan till repositoryt 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

Publicera:

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 container-images

Varje container-image i registret skannas med Trivy i en daglig genomgång. Resultaten visas under Säkerhet › Fynd › Container-images. Se Skanning av container-images för vad som skannas och hur du spärrar hämtningar, och Skadliga paket för kontrollen av skadlig kod i images.

Lagringstid och rensning

Paket sparas som standard på obestämd tid.

• Ta bort en version i gränssnittet: paketets detaljsida → Delete version.
• Ta bort via API: DELETE https://frem.sh/api/v1/packages/<org>/<type>/<name>/<version>
• Massrensning: Organisationens administration → Paket → Städregler, matcha taggar med reguljära uttryck, behåll de senaste N versionerna.

Lagringskvot

Det som beroendeproxyn cachar räknas mot samma paketpool, bredvid dina egna paket. Se Lagringsgränser och kvoter.

Korsreferenser

• Säkerhet och leveranskedja, konfiguration av skanning av container-images
• CI-runners, publicera paket från jobb i workflows
• Publikt REST API, programmatisk pakethantering