Pakketten publiceren

5 minuten

Door pakketten te publiceren naar GitHub Packages, kunt u codebibliotheken, containerinstallatiekopieën en afhankelijkheden delen met uw team of het publiek. GitHub Packages maakt gebruik van systeemeigen opdrachten voor pakkethulpprogramma's, zodat u pakketten kunt publiceren met dezelfde hulpprogramma's en werkstromen die u al kent.

Begrip van pakketregisters

GitHub Packages ondersteunt meerdere pakketecosystemen, elk met een eigen indeling en clienthulpprogramma's:

Taal	Pakketindeling	Pakketclient
JavaScript	package.json	npm
Ruby	Gemfile	juweel
Java	pom.xml	mvn
Java	build.gradle of build.gradle.kts	gradle
.NET	nupkg	dotnet CLI
N.v.t.	Dockerfile	Docker

Pakketmetagegevens en documentatie

Wanneer u een pakket maakt, kunt u uitgebreide metagegevens opgeven op de pakketpagina:

Beschrijving: Duidelijke uitleg over wat het pakket doet
Installatie-instructies: Stapsgewijze handleiding voor consumenten
Gebruiksvoorbeelden: Codevoorbeelden met veelvoorkomende use cases
Afhankelijkheden: Vereiste pakketten en versies
Licentiegegevens: Juridische voorwaarden voor pakketgebruik
Versiegeschiedenis: Wijzigingenlogboek van updates en oplossingen

Goede documentatie helpt mensen die het pakket gebruiken, begrijpen hoe ze het pakket en de doeleinden ervan kunnen gebruiken. Overweeg het volgende:

Snelstartgids: Gebruikers snel aan de slag laten gaan
API-verwijzing: Gedetailleerde documentatie van openbare interfaces
Tips voor probleemoplossing: Veelvoorkomende problemen en oplossingen
Migratiehandleidingen: Hoe u kunt upgraden tussen hoofdversies

Beveiligingsadviezen

Als een nieuwe pakketversie een beveiligingsprobleem oplost, kunt u een beveiligingsadvies publiceren naar uw opslagplaats. Hiermee worden gebruikers op de hoogte van het beveiligingsprobleem en worden richtlijnen geboden voor het upgraden naar beveiligde versies.

Tip

U kunt een opslagplaats verbinden met meer dan één pakket. Een monorepo kan bijvoorbeeld meerdere npm-pakketten of een Docker-installatiekopie naast een NuGet-pakket publiceren. Zorg ervoor dat de README en beschrijving informatie over elk pakket verstrekken om verwarring te voorkomen.

Publicatiewerkstroom

Als u een pakket wilt publiceren naar GitHub Packages, voert u de volgende drie kernstappen uit:

1. Maak een persoonlijk toegangstoken (PAT)

Verificatie is vereist voor het publiceren van pakketten. Maak een persoonlijk toegangstoken met de juiste toegangsrechten:

write:packages: Vereist voor het publiceren van pakketten
read:packages: Vereist om pakketten te downloaden
delete:packages: Vereist om pakketversies te verwijderen
repo: Vereist voor pakketten die zijn gericht op privéopslagplaatsen

Een PAT aanmaken:

Ga naar Instellingen → Developer-instellingen → Persoonlijke toegangstokens
Klik op Nieuw token genereren (klassiek)
Selecteer de vereiste scopes volgens uw behoeften
Een vervaldatum instellen (korter is veiliger)
Kopieer het token onmiddellijk (u ziet het niet meer)

Zie Een persoonlijk toegangstoken maken voor gedetailleerde instructies.

2. Verifiëren bij GitHub Packages

Gebruik uw PAT om te verifiëren bij uw pakketclient. Verificatiemethoden variëren per pakkettype, maar meestal gaat het om het configureren van een inloggegevensbestand of omgevingsvariabele.

Aanbevolen beveiligingsprocedures:

Nooit tokens doorvoeren in broncode: Omgevingsvariabelen of beveiligde opslag van referenties gebruiken
Minimale vereiste scopes gebruiken: Niet meer machtigingen verlenen dan nodig is
Regelmatig tokens draaien: Vervaldatums instellen en periodiek verlengen
Organisatiegeheimen gebruiken: Voor GitHub Actions, sla PAT's op als versleutelde geheimen

3. Het pakket publiceren

Gebruik de systeemeigen opdrachten van uw pakketclient om te publiceren. De specifieke opdracht is afhankelijk van uw pakkettype (npm, NuGet, Maven, Docker, enzovoort).

Controlelijst voor publiceren:

Versienummer volgt semantische versieherziening (MAJOR.MINOR.PATCH)
Pakketmetagegevens zijn voltooid (beschrijving, auteur, licentie)
Afhankelijkheden worden correct opgegeven met versiebeperkingen
Documentatie is opgenomen (README, API-verwijzing)
De tests zijn geslaagd voordat ze worden gepubliceerd
Pakketnaam conflicteert niet met bestaande pakketten

Zie Werken met een GitHub Packages-register voor registerspecifieke instructies.

NuGet-pakketten publiceren

NuGet-pakketten worden gebruikt voor .NET-toepassingen en -bibliotheken. U kunt ze publiceren met behulp van de dotnet CLI.

Verificatie configureren

Maak een nuget.config-bestand in uw projectmap om GitHub Packages op te geven als bron:

<?xml version="1.0" encoding="utf-8"?>
<configuration>
    <packageSources>
        <clear />
        <add key="github" value="https://nuget.pkg.github.com/OWNER/index.json" />
    </packageSources>
    <packageSourceCredentials>
        <github>
            <add key="Username" value="USERNAME" />
            <add key="ClearTextPassword" value="TOKEN" />
        </github>
    </packageSourceCredentials>
</configuration>

Configuratieparameters:

EIGENAAR: GitHub-gebruikersnaam of organisatienaam die eigenaar is van de opslagplaats
GEBRUIKERSNAAM: Uw GitHub-gebruikersnaam
TEKEN: Uw persoonlijke toegangstoken met write:packages bereik

Notitie

Vervang USERNAME door de naam van uw persoonlijke account op GitHub, TOKEN door uw PAT en OWNER door de naam van het gebruikers- of organisatieaccount dat eigenaar is van de opslagplaats van uw project.

Het pakket publiceren

U kunt publiceren met behulp van twee methoden:

Methode 1: nuget.config-bestand gebruiken

dotnet nuget push "bin/Release/OctocatApp.1.0.0.nupkg" --source "github"

Methode 2: De optie --api-key gebruiken

dotnet nuget push "bin/Release/OctocatApp.1.0.0.nupkg" --api-key YOUR_GITHUB_PAT --source "github"

Best practices voor NuGet-publicatie:

Gebruik de releaseconfiguratie: bouw met voor geoptimaliseerde pakketten
Symbolen opnemen: Symbolenpakketten (.snupkg) publiceren voor ondersteuning voor foutopsporing
Versie automatisch: MSBuild-eigenschappen gebruiken om te versien van Git-tags
Pakket valideren: Installatie van het pakket testen voordat u publiceert
Wijzigingen die fouten veroorzaken in documenten: Releaseopmerkingen bijwerken voor belangrijke versiewijzigingen

NPM-pakketten publiceren

npm-pakketten worden gebruikt voor JavaScript- en Node.js-toepassingen. U kunt ze publiceren met behulp van de NPM CLI.

Verificatie configureren

U hebt twee verificatieopties:

Optie 1: ~/.npmrc-bestand bewerken

Voeg uw PAT toe aan het NPMRC-bestand per gebruiker :

//npm.pkg.github.com/:_authToken=TOKEN

Maak een nieuw ~/.npmrc-bestand als deze nog niet bestaat. Met deze methode worden referenties wereldwijd opgeslagen voor alle projecten.

Optie 2: Aanmelden via opdrachtregel

Gebruik de npm-aanmeldingsopdracht voor interactieve verificatie:

$ npm login --scope=@OWNER --registry=https://npm.pkg.github.com

> Username: USERNAME
> Password: TOKEN
> Email: PUBLIC-EMAIL-ADDRESS

Verificatieparameters:

GEBRUIKERSNAAM: Uw GitHub-gebruikersnaam
TEKEN: Uw persoonlijke toegangstoken met write:packages bereik
OPENBAAR E-MAILADRES: Uw e-mailadres (openbaar of privé)
EIGENAAR: GitHub-gebruikersnaam of -organisatie voor scoped pakketten

Notitie

Vervang GEBRUIKERSNAAM door uw GitHub-gebruikersnaam, TOKEN door uw PAT en PUBLIC-EMAIL-ADDRESS door uw e-mailadres.

package.json configureren

Zorg ervoor dat uw package.json het juiste register en het juiste bereik bevat:

{
  "name": "@OWNER/package-name",
  "version": "1.0.0",
  "repository": {
    "type": "git",
    "url": "https://github.com/OWNER/REPOSITORY.git"
  },
  "publishConfig": {
    "registry": "https://npm.pkg.github.com"
  }
}

Het pakket publiceren

Gebruik de standaard-npm-publicatieopdracht :

npm publish

Aanbevolen procedures voor npm-publicatie:

Bereikpakketten gebruiken: Voorvoegsel met @owner/ om naamconflicten te voorkomen
Testen voordat u publiceert: Het .tgz-bestand lokaal uitvoeren npm pack en testen
.npmignore gebruiken: Onnodige bestanden uitsluiten om de pakketgrootte te verkleinen
Versie met npm: Gebruiken npm version patch/minor/major om versies bij te werken
Publiceren vanuit CI/CD: Publicatie automatiseren met GitHub Actions

Gepubliceerde pakketten weergeven

Nadat u een pakket hebt gepubliceerd, kunt u het bekijken op GitHub:

Ga naar uw opslagplaats
Klik op Pakketten in de zijbalk
Selecteer uw pakket om details, versies en downloadstatistieken weer te geven

Zie Codertocat/hello-world-npm voor een voorbeeld.

Zie Werken met het npm-register voor volledige instructies.

Pakketpublicatie automatiseren met GitHub Actions

U kunt pakketpublicatie automatiseren met behulp van GitHub Actions-werkstromen . Dit zorgt ervoor dat pakketten automatisch worden gepubliceerd wanneer code wordt gewijzigd.

Voorbeeldwerkstroom voor npm

name: Publish Package

on:
  release:
    types: [created]

jobs:
  publish:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: write
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: "18"
          registry-url: "https://npm.pkg.github.com"
      - run: npm ci
      - run: npm publish
        env:
          NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Voorbeeldwerkstroom voor NuGet

name: Publish Package

on:
  release:
    types: [created]

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-dotnet@v4
        with:
          dotnet-version: "8.0.x"
      - run: dotnet pack -c Release
      - run: dotnet nuget push "**/*.nupkg" --source github --api-key ${{ secrets.GITHUB_TOKEN }}

Voordelen van geautomatiseerd publiceren:

Consistentie: Elke release maakt automatisch een pakket
Snelheid: Geen handmatige stappen vereist om te publiceren
Traceerbaarheid: Pakketversies komen overeen met Git-tags
Kwaliteitspoorten: Tests uitvoeren voordat u publiceert
Veiligheid: Ingebouwde GITHUB_TOKEN gebruiken in plaats van PAT's

Aanvullende bronnen

Zie voor meer informatie:

Werken met de Container Registry - Docker- en OCI-images publiceren.
Werken met een GitHub Packages-register - Volledige handleiding voor alle ondersteunde registers.
Informatie over GitHub-beveiligingsadviezen : beveiligingsadviezen publiceren voor beveiligingsproblemen.
Werken met het NuGet-register - Gedetailleerde NuGet-publicatiehandleiding.
Werken met het npm-register - Gedetailleerde npm-publicatiehandleiding.

Feedback

Is deze pagina nuttig?