> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/go-gitea/gitea/llms.txt
> Use this file to discover all available pages before exploring further.

# Package Registry

> Built-in multi-format package registry supporting Docker, npm, Maven, PyPI, NuGet, and more

## 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:

<CardGroup cols={3}>
  <Card title="Container" icon="docker">
    Docker and OCI-compatible container images
  </Card>

  <Card title="npm" icon="node-js">
    Node.js packages for JavaScript/TypeScript
  </Card>

  <Card title="Maven" icon="java">
    Java packages and dependencies
  </Card>

  <Card title="PyPI" icon="python">
    Python packages (pip)
  </Card>

  <Card title="NuGet" icon="microsoft">
    .NET packages
  </Card>

  <Card title="Go" icon="golang">
    Go modules
  </Card>

  <Card title="Cargo" icon="rust">
    Rust crates
  </Card>

  <Card title="Composer" icon="php">
    PHP packages
  </Card>

  <Card title="RubyGems" icon="gem">
    Ruby gems
  </Card>

  <Card title="Helm" icon="dharmachakra">
    Kubernetes charts
  </Card>

  <Card title="Debian" icon="ubuntu">
    .deb packages
  </Card>

  <Card title="RPM" icon="redhat">
    .rpm packages
  </Card>
</CardGroup>

### Package Type Implementation

```go theme={null}
// 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

<Steps>
  <Step title="Enable Package Registry">
    Instance administrators must enable packages in Gitea configuration:

    ```ini theme={null}
    [packages]
    ENABLED = true
    ```
  </Step>

  <Step title="Configure Storage">
    Set up storage backend for package files (local, S3, etc.)
  </Step>

  <Step title="Set Quotas (Optional)">
    Configure storage quotas per user/organization:

    ```ini theme={null}
    [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
    ```
  </Step>
</Steps>

## Docker / Container Registry

### Configuring Docker Client

<Tabs>
  <Tab title="Docker Login">
    ```bash theme={null}
    # Login to Gitea container registry
    docker login gitea.example.com

    # Enter username and password/token
    ```
  </Tab>

  <Tab title="Push Image">
    ```bash theme={null}
    # 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
    ```
  </Tab>

  <Tab title="Pull Image">
    ```bash theme={null}
    # 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
    ```
  </Tab>
</Tabs>

### Multi-Architecture Images

```bash theme={null}
# 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

<Steps>
  <Step title="Configure npm Client">
    ```bash theme={null}
    # 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
    ```
  </Step>

  <Step title="Authenticate">
    ```bash theme={null}
    # Login to Gitea npm registry
    npm login --scope=@username --registry=https://gitea.example.com/api/packages/username/npm/
    ```
  </Step>

  <Step title="Publish Package">
    ```bash theme={null}
    # Publish package
    npm publish
    ```
  </Step>
</Steps>

### Installing npm Packages

```bash theme={null}
# Install from Gitea registry
npm install @username/package-name

# Install specific version
npm install @username/package-name@1.0.0
```

## Maven Packages

### Publishing Maven Packages

Configure `pom.xml`:

```xml theme={null}
<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`:

```xml theme={null}
<settings>
  <servers>
    <server>
      <id>gitea</id>
      <username>your-username</username>
      <password>your-token</password>
    </server>
  </servers>
</settings>
```

Deploy package:

```bash theme={null}
mvn deploy
```

### Using Maven Packages

```xml theme={null}
<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

<Steps>
  <Step title="Install Twine">
    ```bash theme={null}
    pip install twine
    ```
  </Step>

  <Step title="Build Package">
    ```bash theme={null}
    python setup.py sdist bdist_wheel
    ```
  </Step>

  <Step title="Configure .pypirc">
    ```ini theme={null}
    [distutils]
    index-servers = gitea

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

  <Step title="Upload Package">
    ```bash theme={null}
    twine upload -r gitea dist/*
    ```
  </Step>
</Steps>

### Installing Python Packages

```bash theme={null}
# 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

```bash theme={null}
# 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

```bash theme={null}
# Install package
dotnet add package PackageName --source gitea
```

## Go Modules

### Using Go Packages

Gitea automatically serves Go modules from repository:

```bash theme={null}
# 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/package@v1.0.0
```

## Package Management

### Package Creation Flow

```go theme={null}
// 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

<Tabs>
  <Tab title="Repository Packages">
    * Navigate to **Packages** tab in repository
    * View all packages in the repository
    * See package versions
    * Download package files
  </Tab>

  <Tab title="User/Org Packages">
    * View packages under user or organization
    * All packages across repositories
    * Centralized package management
    * Package statistics
  </Tab>
</Tabs>

## Package Versions

### Version Management

<CardGroup cols={2}>
  <Card title="Semantic Versioning" icon="tag">
    * Follow semver (v1.2.3)
    * Major.Minor.Patch
    * Pre-release tags (v1.0.0-beta.1)
    * Build metadata (v1.0.0+build.123)
  </Card>

  <Card title="Version Operations" icon="list">
    * View all versions
    * Download specific versions
    * Delete old versions
    * View version metadata
  </Card>
</CardGroup>

### Version Listing

```bash theme={null}
# 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:

<Steps>
  <Step title="Generate Token">
    Navigate to **Settings** → **Applications** → **Generate New Token**
  </Step>

  <Step title="Select Scopes">
    Choose appropriate scopes:

    * `read:package` - Read packages
    * `write:package` - Publish packages
    * `delete:package` - Delete packages
  </Step>

  <Step title="Use Token">
    Use token in package client configuration instead of password
  </Step>
</Steps>

## Package Cleanup

### Cleanup Rules

Automate package cleanup to manage storage:

<Accordion title="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**

  ```ini theme={null}
  [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
</Accordion>

## Storage Quotas

Control package storage usage:

<CardGroup cols={2}>
  <Card title="User Quotas" icon="user">
    * Total storage limit per user
    * Per-package-type limits
    * Soft and hard limits
    * Quota warnings
  </Card>

  <Card title="Organization Quotas" icon="building">
    * Organization-wide limits
    * Shared among members
    * Per-package-type limits
    * Usage monitoring
  </Card>
</CardGroup>

## Package Visibility

<Tabs>
  <Tab title="Public Packages">
    * Accessible without authentication
    * Listed in public package index
    * Can be used by anyone
    * Promotes open source sharing
  </Tab>

  <Tab title="Private Packages">
    * Requires authentication
    * Only accessible to authorized users
    * Not listed publicly
    * Suitable for proprietary code
  </Tab>

  <Tab title="Internal Packages">
    * Accessible to logged-in users
    * Not available to anonymous users
    * Visible to organization members
    * Balances security and convenience
  </Tab>
</Tabs>

## Package API

### REST API Endpoints

```bash theme={null}
# 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:

```yaml theme={null}
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

<Accordion title="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
</Accordion>

## Troubleshooting

<CardGroup cols={2}>
  <Card title="Authentication Issues" icon="key">
    * Verify token has correct scopes
    * Check token expiration
    * Confirm username/token format
    * Review registry URL
  </Card>

  <Card title="Publishing Failures" icon="triangle-exclamation">
    * Check package format
    * Verify version doesn't exist
    * Confirm storage quota
    * Review package size limits
  </Card>
</CardGroup>

## See Also

* [Actions](/features/actions) - Automate package publishing
* [Repositories](/features/repositories) - Source code management
* [API Documentation](/api-reference) - Package registry API