Pakke-registry

Oversat fra den engelske original. Hvis de to versioner er forskellige, gælder den engelske. Oversættelsen er endnu ikke korrekturlæst af en dansk modersmålsbruger.

fremforge har et indbygget pakke-registry. Pakkerne ligger i din organisation. Der findes ingen langlivede registry-tokens: CI-jobs bruger det token, som hvert Forgejo Actions-job allerede får, og personer bruger fremforge CLI’en, som giver hvert værktøj et token, der højst gælder i en time.

Alle registries serveres fra én host, frem.sh, under en sti pr. organisation og pakketype:

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

Der er ingen separate hostnavne pr. økosystem. Container-images er den eneste undtagelse fra stireglen: de bruger OCI-registryet direkte på frem.sh.

Understøttede pakketyper

Stierne i tabellen er relative til https://frem.sh/api/packages/<org>/. Container-images og Go-moduler er undtagelserne og står med fuld sti.

Alle typer i tabellen er slået til for alle organisationer. Conda, CRAN, Conan, Chef, Pub, Swift, Vagrant, Go-modulproxyen og generiske filer har endnu ingen opskrift på denne side: peg klienten på stien i tabellen, og godkend dig som beskrevet under andre pakketyper.

For en privat organisation svarer alle stierne ovenfor 401 uden et token, også indeks- og nøglefilerne. Kun NuGets serviceindeks (nuget/index.json) kan læses uden, fordi NuGet-klienten henter det, før den godkender sig.

Godkendelse

Du kan godkende dig på tre måder:

API-tokens (ffp_…) accepteres ikke af registries. De gælder kun fremforges REST API. Der udstedes ikke personlige access tokens med pakke-scopes: brug en registry robot.

Udgivelse fra Forgejo Actions

Hvert jobs automatiske token kan bruge registryet hos ejeren af jobbets repository:

• Læse alle ejerens pakker (den organisation, repositoryet tilhører).
• Skrive til en pakke, der er knyttet til jobbets eget repository, eller oprette en ny pakke. En pakke, som et job opretter, knyttes automatisk til jobbets repository.
• Pull requests fra forks får kun læseadgang, aldrig skriveadgang.

Du skal ikke erklære noget: der er ingen permissions: packages: write at tilføje. Skrivning til en pakke, der er knyttet til et andet repository, eller til en pakke, der ikke er knyttet til noget repository, afvises med 403:

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

Vil du udgive en eksisterende pakke, der ikke er knyttet til noget repository, fra et job, så knyt den først til repositoryet på pakkens Settings-side.

Tokenet fungerer som adgangskode (med et vilkårligt brugernavn) for alle klienter og som Bearer-token for npm. Her er ét workflow, der udgiver hver af de almindelige typer:

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 tokenet fra miljøet, så filen kan godt committes:

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

Til Gradle sender du de samme værdier som properties, for eksempel -PfremforgeUsername="${{ github.actor }}" -PfremforgePassword="$TOKEN", og læser dem som vist under Gradle.

På din egen maskine: fremforge auth

Installér fremforge CLI’en, og log ind. Login går gennem din organisations single sign-on 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

Login med device-kode kræver CLI 0.5.0 eller nyere.

Sæt derefter hvert værktøj op én gang:

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

Hvad configure gør for hvert værktøj:

Helperen og keyring-kommandoen er små scripts i ~/.local/bin (på Windows %LOCALAPPDATA%\fremforge\bin), som kalder CLI’en. configure advarer dig, hvis den mappe ikke er på din PATH.

Tokenet fornyes automatisk. npm, Maven og Gradle kan ikke selv bede om et nyt token, så kopien i deres konfiguration skrives om, hver gang du kører en fremforge-kommando, eller eksplicit med:

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

Kør den før et build, for eksempel som et npm-preinstall-script ("preinstall": "fremforge auth refresh --quiet") eller som et pre-build-trin i din IDE.

Selve dit login (refresh-tokenet, der gælder i 30 dage) gemmes i styresystemets nøglering: macOS Keychain, Windows Credential Manager eller Secret Service på Linux. Hvor der ikke er nogen nøglering, eller den ikke kan bruges, falder CLI’en tilbage til ~/.config/fremforge/auth.json med mode 600 og siger det. Understøttelsen af nøgleringen på macOS og Windows er ny i 0.5.0 og er indtil videre kun afprøvet med automatiske tests, ikke på rigtige maskiner; fil-fallbacket er det, der holder det kørende, hvis en nøglering nægter.

fremforge auth logout fjerner login og alle de legitimationsoplysninger, configure har skrevet: npm-, Maven- og Gradle-tokenlinjerne, docker-indgangen under credHelpers samt helper- og keyring-scriptene. Den fjerner kun det, fremforge selv har skrevet, genkendt på en fremforge-managed-kommentar, så dine egne linjer bliver stående. Den kan ikke tilbagekalde tokenet på serveren: et access token, der allerede er udstedt, er gyldigt, indtil det udløber, højst 1 time. Vil du afslutte login med det samme, så fjern fremforge-cli under Settings › Applications på frem.sh.

Andre pakketyper

CLI’en sætter docker, pip/uv, npm, Maven og Gradle op. De øvrige klienter på denne side (NuGet, Composer, RubyGems, Cargo, Helm, apt, dnf, apk, pacman og Go) har endnu ingen helper: udgiv dem fra Forgejo Actions, hvor <token> i opskrifterne nedenfor er ${{ secrets.FORGEJO_TOKEN }} og <username> er ${{ github.actor }}.

npm

Læg en .npmrc-fil i roden af dit projekt:

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

fremforge auth configure npm leverer tokenet (se Godkendelse); i Actions tilføjer du _authToken-linjen fra workflowet ovenfor.

<scope> er din pakkes npm-scope. Den behøver ikke at svare til organisationens navn: organisationen internal-fremverk udgiver for eksempel @fremverk/*-pakker.

Udgiv:

npm publish

Installér:

npm install @<scope>/package-name

Docker / OCI

På din egen maskine kører du fremforge auth configure docker én gang; der er ingen docker login. I Actions logger du ind med jobbets token som i workflowet ovenfor.

Push og pull:

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

Maven

Tilføj distributions-repositoryet i pom.xml:

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

Vil du installere derfra, så tilføj den samme URL under <repositories> med samme <id>.

Legitimationen kommer fra fremforge auth configure maven, som skriver server-indgangen fremforge i ~/.m2/settings.xml, eller i Actions fra en settings-fil, der læser jobbets token (se Udgivelse fra Forgejo Actions).

Gradle

Erklær repositoryet, og læs legitimationen fra de properties, 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

Registrér kilden:

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

PyPI

På din egen maskine skal du, efter fremforge auth configure pip, bede pip og uv om at spørge keyring. pip kræver brugernavnet i indeks-URL’en; brug dit fremforge-brugernavn:

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

Udgiv fra Actions med twine, som i workflowet ovenfor:

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

Composer

Tilføj repositoryet i composer.json:

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

Læg legitimationen i auth.json i roden af dit projekt:

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

Udgiv et pakkearkiv. Query-parameteren version er nødvendig, medmindre composer.json i arkivet angiver 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øgle:

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

Cargo

Tilføj registryet i .cargo/config.toml:

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

Læg legitimationen i ~/.cargo/credentials.toml:

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

Udgiv:

cargo publish --registry fremforge

Go-moduler

Go-moduler serveres direkte fra repositoryets URL:

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

Er dit Go-modul privat, så markér det som privat, så Go-værktøjskæden springer den offentlige proxy og checksum-databasen over:

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

GOPRIVATE er Go’s officielle miljøvariabel til formålet; den slår GOPROXY- og GOSUMDB-opslag fra for matchende stier i én indstilling. For at go get kan godkende sig, skal Git have en legitimation til frem.sh: i Actions checkout-tokenet, på din egen maskine dit normale Git-login.

Helm

Helm-charts kan gemmes i to former, og du kan bruge den ene, den anden eller begge:

• Som OCI-artefakter i container-registryet på frem.sh, ved siden af dine images: oci://frem.sh/<org>/<chart>.
• I et klassisk chart-repository (index.yaml plus chart-arkiver) på https://frem.sh/api/packages/<org>/helm.

De to er adskilte lagre. Et chart, der er pushet som OCI, optræder ikke i den klassiske index.yaml, og omvendt.

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

Helm-charts som OCI-artefakter

Kræver Helm 3.8 eller nyere. Log ind én gang, og push derefter det pakkede chart til organisationen. Chartets navn og version bliver til 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>

Installér eller hent direkte fra registryet; der er 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 gemmes som en container-pakke med navnet <chart>, så det står under organisationens Pakker sammen med dine images, og et pull af det går gennem den samme malware-scan-kontrol som et image-pull.

Vil du fjerne en chart-version, så slet den med pakke-API’et, type container. Et push opretter også en version, der er navngivet efter manifestets digest (sha256:…); slet også den, ellers bliver chartets indhold liggende.

Klassisk Helm-chart-repository

Udgiv 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 upload svarer 201.

En udgivet chart-version kan ikke overskrives. Uploader du den samme version igen med andet indhold, svarer den 409 med en besked, der starter med immutable package: og siger, at filen allerede er udgivet; intet bliver erstattet. Vil du udgive en ændring, så hæv version i Chart.yaml, pak chartet igen, og upload den nye version. Uploader du præcis det samme arkiv igen, som når et CI-job køres igen, svarer den 201 og ændrer intet. Se Uforanderlige releases.

Tilføj repositoryet, og installér derfra. For en privat organisation svarer indekset 401 uden et 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 version med pakke-API’et, type helm. Nummeret på en slettet version forbliver brugt: uploader du den version igen, uanset indhold, svarer den 409.

Debian

Repositoryet er signeret. Den offentlige nøgle 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 organisation giver du apt tokenet i /etc/apt/auth.conf.d/fremforge.conf (machine frem.sh login <username> password <token>).

Udgiv en .deb i en distribution og komponent efter eget valg:

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

Tilføj repositoryet. Den .repo-fil, det serverer, peger gpgkey på signeringsnøglen, så dnf verificerer pakkerne:

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

For en privat organisation tilføjer du username=<username> og password=<token> i repositoryets sektion i /etc/yum.repos.d/.

Udgiv:

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

Installér signeringsnøglen, og tilføj derefter repositoryet. <branch> og <repository> er navne, du selv vælger, når du udgiver, 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

Udgiv:

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

Arch

Importér signeringsnøglen, og tilføj derefter 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

Udgiv:

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>

Scanning af container-images

Alle container-images i registryet scannes med Trivy i en daglig gennemgang. Resultaterne vises under Administration → Code security → Container-images. Se Scanning af container-images for, hvad der scannes, og hvordan du blokerer pulls, og Skadelige pakker for malware-kontrollen af images.

Opbevaring og oprydning

Pakker opbevares som standard på ubestemt tid.

• Slet en version i brugerfladen: pakkens detaljeside → Delete version.
• Slet via API: DELETE https://frem.sh/api/v1/packages/<org>/<type>/<name>/<version>
• Masseoprydning: Administration → Packages → Cleanup policies; match tags med et regulært udtryk, og behold de seneste N versioner.

Lagerkvote

Når dependency-proxyen er tilgængelig for din organisation, tæller de images, den cacher, med i den samme pakkepulje, ved siden af dine egne pakker. Se Lagergrænser og kvoter.

Krydshenvisninger

• Sikkerhed og forsyningskæde, konfiguration af scanning af container-images
• CI-runnere, udgivelse af pakker fra workflow-jobs
• Offentligt REST API, programmatisk pakkehåndtering