Package Registry

Overview

Gitea includes a comprehensive package registry that supports multiple package formats, enabling you to host and distribute your software packages alongside your source code. This integrated approach simplifies dependency management and distribution workflows.

Supported Package Types

Gitea supports a wide variety of package formats:

Container

Docker and OCI-compatible container images

npm

Node.js packages for JavaScript/TypeScript

Maven

Java packages and dependencies

PyPI

Python packages (pip)

NuGet

.NET packages

Go

Go modules

Cargo

Rust crates

Composer

PHP packages

RubyGems

Ruby gems

Helm

Kubernetes charts

Debian

.deb packages

RPM

.rpm packages

Package Type Implementation

// From models/packages/package.go
type Type string

const (
    TypeAlpine    Type = "alpine"
    TypeArch      Type = "arch"
    TypeCargo     Type = "cargo"
    TypeChef      Type = "chef"
    TypeComposer  Type = "composer"
    TypeConan     Type = "conan"
    TypeConda     Type = "conda"
    TypeContainer Type = "container"
    TypeCran      Type = "cran"
    TypeDebian    Type = "debian"
    TypeGeneric   Type = "generic"
    TypeGo        Type = "go"
    TypeHelm      Type = "helm"
    TypeMaven     Type = "maven"
    TypeNpm       Type = "npm"
    TypeNuGet     Type = "nuget"
    TypePub       Type = "pub"
    TypePyPI      Type = "pypi"
    TypeRpm       Type = "rpm"
    TypeRubyGems  Type = "rubygems"
    TypeSwift     Type = "swift"
    TypeVagrant   Type = "vagrant"
)

Enabling Packages

Enable Package Registry

Instance administrators must enable packages in Gitea configuration:

[packages]
ENABLED = true

Configure Storage

Set up storage backend for package files (local, S3, etc.)

Set Quotas (Optional)

Configure storage quotas per user/organization:

[packages]
LIMIT_TOTAL_OWNER_SIZE = 10GB
LIMIT_SIZE_ALPINE = 1GB
LIMIT_SIZE_CARGO = 2GB
LIMIT_SIZE_COMPOSER = 1GB
LIMIT_SIZE_CONTAINER = 5GB
LIMIT_SIZE_NPM = 2GB

Docker / Container Registry

Configuring Docker Client

Docker Login
Push Image
Pull Image

# Tag image with Gitea registry
docker tag myapp:latest gitea.example.com/username/myapp:latest

# Push to registry
docker push gitea.example.com/username/myapp:latest

# Push with version tag
docker tag myapp:latest gitea.example.com/username/myapp:v1.0.0
docker push gitea.example.com/username/myapp:v1.0.0

# Pull from Gitea registry
docker pull gitea.example.com/username/myapp:latest

# Pull specific version
docker pull gitea.example.com/username/myapp:v1.0.0

Multi-Architecture Images

# Build multi-arch image
docker buildx build --platform linux/amd64,linux/arm64,linux/arm/v7 \
  -t gitea.example.com/username/myapp:latest \
  --push .

npm Packages

Publishing npm Packages

Configure npm Client

# Set registry for scope
npm config set @username:registry https://gitea.example.com/api/packages/username/npm/

# Or configure in .npmrc
echo "@username:registry=https://gitea.example.com/api/packages/username/npm/" >> .npmrc

Authenticate

# Login to Gitea npm registry
npm login --scope=@username --registry=https://gitea.example.com/api/packages/username/npm/

Publish Package

# Publish package
npm publish

Installing npm Packages

# Install from Gitea registry
npm install @username/package-name

# Install specific version
npm install @username/[email protected]

Maven Packages

Publishing Maven Packages

Configure pom.xml:

<project>
  <distributionManagement>
    <repository>
      <id>gitea</id>
      <name>Gitea Maven Repository</name>
      <url>https://gitea.example.com/api/packages/username/maven</url>
    </repository>
  </distributionManagement>
</project>

Configure ~/.m2/settings.xml:

<settings>
  <servers>
    <server>
      <id>gitea</id>
      <username>your-username</username>
      <password>your-token</password>
    </server>
  </servers>
</settings>

Deploy package:

mvn deploy

Using Maven Packages

<repositories>
  <repository>
    <id>gitea</id>
    <url>https://gitea.example.com/api/packages/username/maven</url>
  </repository>
</repositories>

<dependencies>
  <dependency>
    <groupId>com.example</groupId>
    <artifactId>mylib</artifactId>
    <version>1.0.0</version>
  </dependency>
</dependencies>

Python / PyPI Packages

Publishing Python Packages

Install Twine

pip install twine

Build Package

python setup.py sdist bdist_wheel

Configure .pypirc

[distutils]
index-servers = gitea

[gitea]
repository = https://gitea.example.com/api/packages/username/pypi
username = your-username
password = your-token

Upload Package

twine upload -r gitea dist/*

Installing Python Packages

# Install from Gitea
pip install --index-url https://gitea.example.com/api/packages/username/pypi/simple package-name

# Or configure in pip.conf
[global]
index-url = https://gitea.example.com/api/packages/username/pypi/simple

NuGet Packages

Publishing NuGet Packages

# Add source
dotnet nuget add source https://gitea.example.com/api/packages/username/nuget/index.json \
  --name gitea \
  --username your-username \
  --password your-token

# Pack project
dotnet pack

# Push package
dotnet nuget push package.nupkg --source gitea

Installing NuGet Packages

# Install package
dotnet add package PackageName --source gitea

Go Modules

Using Go Packages

Gitea automatically serves Go modules from repository:

# Set GOPROXY to use Gitea
export GOPROXY=https://gitea.example.com/api/packages/username/go,direct

# Import in go.mod
import "gitea.example.com/username/package"

# Install dependencies
go get gitea.example.com/username/[email protected]

Package Management

Package Creation Flow

// From services/packages/packages.go
type PackageCreationInfo struct {
    PackageInfo
    SemverCompatible  bool
    Creator           *user_model.User
    Metadata          any
    PackageProperties map[string]string
    VersionProperties map[string]string
}

func CreatePackageAndAddFile(ctx context.Context, 
                             pvci *PackageCreationInfo, 
                             pfci *PackageFileCreationInfo) (
    *packages_model.PackageVersion, 
    *packages_model.PackageFile, 
    error) {
    
    return createPackageAndAddFile(ctx, pvci, pfci, false)
}

func createPackageAndAddFile(ctx context.Context, 
                            pvci *PackageCreationInfo, 
                            pfci *PackageFileCreationInfo, 
                            allowDuplicate bool) (
    *packages_model.PackageVersion, 
    *packages_model.PackageFile, 
    error) {
    
    // Create package version
    pv, created, err := createPackageAndVersion(ctx, pvci, allowDuplicate)
    if err != nil {
        return nil, nil, err
    }
    
    // Add file to package
    pf, pb, blobCreated, err := addFileToPackageVersion(ctx, pv, 
                                                        &pvci.PackageInfo, pfci)
    return pv, pf, err
}

Viewing Packages

Repository Packages
User/Org Packages

Navigate to Packages tab in repository
View all packages in the repository
See package versions
Download package files

Package Versions

Version Management

Semantic Versioning

Follow semver (v1.2.3)
Major.Minor.Patch
Pre-release tags (v1.0.0-beta.1)
Build metadata (v1.0.0+build.123)

Version Operations

View all versions
Download specific versions
Delete old versions
View version metadata

Version Listing

# List all versions of a package
curl https://gitea.example.com/api/packages/username/npm/@scope/package

# View specific version details
curl https://gitea.example.com/api/packages/username/npm/@scope/package/1.0.0

Authentication

Token-Based Authentication

Create access tokens for package operations:

Generate Token

Navigate to Settings → Applications → Generate New Token

Select Scopes

Choose appropriate scopes:

read:package - Read packages
write:package - Publish packages
delete:package - Delete packages

Use Token

Use token in package client configuration instead of password

Package Cleanup

Cleanup Rules

Automate package cleanup to manage storage:

Cleanup Configuration

Retention Policies

Keep N most recent versions
Delete versions older than X days
Keep versions matching pattern
Delete untagged container images

Configuration Example

[packages]
CLEANUP_ENABLED = true
CLEANUP_INTERVAL = 24h
RETENTION_DAYS = 90
KEEP_COUNT = 10

Manual Cleanup

Delete individual versions
Delete entire packages
Bulk deletion operations
Cleanup orphaned files

Storage Quotas

Control package storage usage:

User Quotas

Total storage limit per user
Per-package-type limits
Soft and hard limits
Quota warnings

Organization Quotas

Organization-wide limits
Shared among members
Per-package-type limits
Usage monitoring

Package Visibility

Public Packages
Private Packages
Internal Packages

Accessible without authentication
Listed in public package index
Can be used by anyone
Promotes open source sharing

Package API

REST API Endpoints

# List packages
GET /api/v1/packages/{owner}

# Get package details
GET /api/v1/packages/{owner}/{type}/{name}/{version}

# Delete package version
DELETE /api/v1/packages/{owner}/{type}/{name}/{version}

# List package files
GET /api/v1/packages/{owner}/{type}/{name}/{version}/files

Integration with Actions

Publish packages automatically with Gitea Actions:

name: Publish Package

on:
  release:
    types: [published]

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18'
          registry-url: 'https://gitea.example.com/api/packages/username/npm/'
      
      - run: npm ci
      - run: npm publish
        env:
          NODE_AUTH_TOKEN: ${{ secrets.GITEA_TOKEN }}

Best Practices

Package Management Guidelines

Versioning

Follow semantic versioning
Tag releases in Git
Document breaking changes
Use pre-release versions for testing

Security

Use access tokens, not passwords
Rotate tokens regularly
Set appropriate visibility
Scan for vulnerabilities
Sign packages when possible

Organization

Use consistent naming conventions
Add package descriptions
Include README files
Link to source repository
Document dependencies

Storage Management

Configure cleanup rules
Monitor storage usage
Delete unused packages
Archive old versions
Use external storage for large packages

Getting Started

Core Features

Administration

User Management

Integrations

​Overview

​Supported Package Types

Container

npm

Maven

PyPI

NuGet

Go

Cargo

Composer

RubyGems

Helm

Debian

RPM

​Package Type Implementation

​Enabling Packages

​Docker / Container Registry

​Configuring Docker Client

​Multi-Architecture Images

​npm Packages

​Publishing npm Packages

​Installing npm Packages

​Maven Packages

​Publishing Maven Packages

​Using Maven Packages

​Python / PyPI Packages

​Publishing Python Packages

​Installing Python Packages

​NuGet Packages

​Publishing NuGet Packages

​Installing NuGet Packages

​Go Modules

​Using Go Packages

​Package Management

​Package Creation Flow

​Viewing Packages

​Package Versions

​Version Management

Semantic Versioning

Version Operations

​Version Listing

​Authentication

​Token-Based Authentication

​Package Cleanup

​Cleanup Rules

​Storage Quotas