Client-Tools für Paketformate konfigurieren

Kurzpfad

1. Bestimme die öffentliche Basis-URL deiner Instanz, zum Beispiel https://packages.example.com.
2. Bestimme den Repository-Namen, den du ansprechen willst, zum Beispiel libs-release.
3. Erzeuge einen passenden User- oder Robot-Token.
4. Setze im jeweiligen Client die richtige Repository-URL aus Kontextpfad und Repository-Namen zusammen.
5. Hinterlege den Token je nach Client als Bearer-Token oder als Passwort für Basic Auth.

Grundmuster für Repository-URLs

In Craftifact setzt sich die URL immer aus Basis-URL, Kontextpfad und Repository-Name zusammen.

Für die aktuell unterstützten Familien sind die Basismuster:

• Maven: https://<instanz>/repository/maven/<repo-name>/
• Gradle: https://<instanz>/repository/maven/<repo-name>/
• Python: https://<instanz>/repository/python/<repo-name>/simple/
• npm: https://<instanz>/repository/npm/<repo-name>/
• OCI: https://<instanz>/v2/<repo-name>/...
• Go beta: Details folgen noch.

Für Docker-Kommandos schreibst du den Kontextpfad v2 normalerweise nicht selbst aus. Der Client verwendet ihn intern, während du im Image-Namen mit Host, Repository-Name und Image-Pfad arbeitest.

Der Konfigurator oben setzt automatisch:

• Basis-URL wie https://packages.example.com
• Instanz-Host wie packages.example.com
• Repository-Name wie libs-release

Als Platzhalter bleiben in den Snippets nur noch:

• TOKEN als erzeugter API- oder Robot-Token
• ROBOT_ID wie acceptance-test

Maven und Gradle

Für Maven und Gradle nutzt du denselben Repository-Kontextpfad:

https://packages.example.com/repository/maven/libs-release/

<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 https://maven.apache.org/xsd/settings-1.0.0.xsd">
  <servers>
    <server>
      <id>craftifact</id>
      <configuration>
        <httpHeaders>
          <property>
            <name>Authorization</name>
            <value>Bearer ${env.CRAFTIFACT_TOKEN}</value>
          </property>
        </httpHeaders>
      </configuration>
    </server>
  </servers>
</settings>

mvn deploy \
  -s settings.xml \
  -DaltDeploymentRepository=craftifact::https://packages.example.com/repository/maven/libs-release/

repositories {
  maven {
    url = uri("https://packages.example.com/repository/maven/libs-release/")
    credentials(HttpHeaderCredentials) {
      name = "Authorization"
      value = "Bearer ${System.getenv('CRAFTIFACT_TOKEN')}"
    }
    authentication {
      header(HttpHeaderAuthentication)
    }
  }
}

publishing {
  repositories {
    maven {
      url = uri("https://packages.example.com/repository/maven/libs-release/")
      credentials(HttpHeaderCredentials) {
        name = "Authorization"
        value = "Bearer ${System.getenv('CRAFTIFACT_TOKEN')}"
      }
      authentication {
        header(HttpHeaderAuthentication)
      }
    }
  }
}

pip und Poetry

Für Python-Clients ist die Simple-Index-URL:

https://packages.example.com/repository/python/libs-release/simple/

[global]
index-url = https://ROBOT_ID:TOKEN@packages.example.com/repository/python/libs-release/simple/

https://__token__:TOKEN@packages.example.com/repository/python/libs-release/simple/

poetry source add --priority=primary craftifact \
  https://packages.example.com/repository/python/libs-release/simple/

poetry config http-basic.craftifact ROBOT_ID TOKEN

poetry config repositories.craftifact \
  https://packages.example.com/repository/python/libs-release/
poetry publish --build --repository craftifact

Docker

Bei OCI ist der technische Kontextpfad immer v2, aber Docker verwendet ihn intern. Für den Login meldest du dich am Registry-Host an, nicht an einer expliziten /v2/-URL.

printf '%s' "$TOKEN" | docker login packages.example.com -u ROBOT_ID --password-stdin

Ein Image adressierst du dann über Host, Repository-Name und Image-Pfad:

packages.example.com/libs-release/IMAGE_PATH:TAG

Beispiel:

docker pull packages.example.com/libs-release/demo/app:1.0.0
docker push packages.example.com/libs-release/demo/app:1.0.0

Dabei gilt intern:

• der Host ist packages.example.com
• der Repository-Name ist libs-oci
• der Image-Pfad ist demo/app
• der Client spricht darunter automatisch die API unter /v2/ an

npm

Für npm ist die Registry-URL:

https://packages.example.com/repository/npm/libs-release/

Ein minimales .npmrc-Beispiel:

registry=https://packages.example.com/repository/npm/libs-release/
always-auth=true
//packages.example.com/repository/npm/libs-release/:_authToken=TOKEN

Wenn du scoped Packages nutzt, bleibt die Basis-URL gleich. Nur der Paketname selbst wird später entsprechend mit Scope verwendet, zum Beispiel @acme/demo.

Praktische Hinweise

• Nicht jeder Client kann Bearer- und Basic-Auth gleich flexibel ausdrücken. Nutze deshalb die Form, die zum Tool passt.
• Für Docker ist der Login auf Host-Ebene normal, obwohl die Registry intern unter v2 arbeitet.
• Für Python-Installationen ist simple/ Teil der URL und darf nicht weggelassen werden.
• Für Poetry-Publishing nutzt du dagegen die Repository-URL ohne simple/.

Verwandte Seiten

• Für SBOM-spezifische Workflows mit Maven, Gradle, Poetry, npm und OCI siehe SBOMs mit Client-Tools erzeugen.
• Für Token-Erzeugung und die Unterschiede zwischen Bearer- und Basic-Auth siehe Robot-Account anlegen und Token nutzen.
• Für allgemeine Paketformat-Regeln siehe Hinweise zu Paketformaten.