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

# Packages API

> API endpoints for Gitea Package Registry

## Overview

Gitea Package Registry provides a unified platform for hosting multiple package types. The Packages API allows you to manage packages, versions, and files across all supported package formats.

## Supported Package Types

Gitea supports the following package registries:

* **alpine** - Alpine Linux packages
* **cargo** - Rust crates
* **chef** - Chef cookbooks
* **composer** - PHP packages
* **conan** - C/C++ packages
* **conda** - Conda packages
* **container** - Docker/OCI container images
* **cran** - R packages
* **debian** - Debian packages
* **generic** - Generic file storage
* **go** - Go modules
* **helm** - Kubernetes Helm charts
* **maven** - Java Maven artifacts
* **npm** - Node.js packages
* **nuget** - .NET packages
* **pub** - Dart packages
* **pypi** - Python packages
* **rpm** - RPM packages
* **rubygems** - Ruby gems
* **swift** - Swift packages
* **vagrant** - Vagrant boxes

## Packages

### List Packages

List all packages for an owner (user or organization).

```bash theme={null}
curl -X GET "https://gitea.example.com/api/v1/packages/{owner}?type=npm" \
  -H "Authorization: token YOUR_TOKEN"
```

<ParamField path="owner" type="string" required>
  Package owner (username or organization name)
</ParamField>

<ParamField query="type" type="string">
  Filter by package type (npm, maven, container, etc.)
</ParamField>

<ParamField query="q" type="string">
  Search query to filter packages by name
</ParamField>

<ParamField query="page" type="integer">
  Page number for pagination (default: 1)
</ParamField>

<ParamField query="limit" type="integer">
  Number of items per page (default: 30)
</ParamField>

<ResponseField name="packages" type="array">
  <ResponseField name="id" type="integer">
    Package ID
  </ResponseField>

  <ResponseField name="type" type="string">
    Package type
  </ResponseField>

  <ResponseField name="name" type="string">
    Package name
  </ResponseField>

  <ResponseField name="version" type="string">
    Latest version
  </ResponseField>

  <ResponseField name="creator" type="object">
    User who created the package
  </ResponseField>

  <ResponseField name="created_at" type="string">
    Creation timestamp
  </ResponseField>

  <ResponseField name="repository" type="object">
    Linked repository (if any)
  </ResponseField>
</ResponseField>

### Get Package

Get details about a specific package version.

```bash theme={null}
curl -X GET "https://gitea.example.com/api/v1/packages/{owner}/{type}/{name}/{version}" \
  -H "Authorization: token YOUR_TOKEN"
```

<ParamField path="type" type="string" required>
  Package type
</ParamField>

<ParamField path="name" type="string" required>
  Package name
</ParamField>

<ParamField path="version" type="string" required>
  Package version
</ParamField>

<ResponseField name="id" type="integer">
  Package version ID
</ResponseField>

<ResponseField name="name" type="string">
  Package name
</ResponseField>

<ResponseField name="version" type="string">
  Package version
</ResponseField>

<ResponseField name="type" type="string">
  Package type
</ResponseField>

<ResponseField name="files" type="array">
  Files included in this version
</ResponseField>

<ResponseField name="metadata" type="object">
  Package-specific metadata (varies by type)
</ResponseField>

### Delete Package

Delete a specific package version.

```bash theme={null}
curl -X DELETE "https://gitea.example.com/api/v1/packages/{owner}/{type}/{name}/{version}" \
  -H "Authorization: token YOUR_TOKEN"
```

<Warning>
  Deleting a package version is permanent and cannot be undone.
</Warning>

## Package Versions

### List Package Versions

List all versions of a specific package.

```bash theme={null}
curl -X GET "https://gitea.example.com/api/v1/packages/{owner}/{type}/{name}" \
  -H "Authorization: token YOUR_TOKEN"
```

<ResponseField name="versions" type="array">
  List of all versions for the package
</ResponseField>

### Get Latest Version

Get the latest version of a package.

```bash theme={null}
curl -X GET "https://gitea.example.com/api/v1/packages/{owner}/{type}/{name}/-/latest" \
  -H "Authorization: token YOUR_TOKEN"
```

## Package Files

### List Package Files

List all files in a package version.

```bash theme={null}
curl -X GET "https://gitea.example.com/api/v1/packages/{owner}/{type}/{name}/{version}/files" \
  -H "Authorization: token YOUR_TOKEN"
```

<ResponseField name="files" type="array">
  <ResponseField name="id" type="integer">
    File ID
  </ResponseField>

  <ResponseField name="name" type="string">
    Filename
  </ResponseField>

  <ResponseField name="size" type="integer">
    File size in bytes
  </ResponseField>

  <ResponseField name="hash_md5" type="string">
    MD5 hash
  </ResponseField>

  <ResponseField name="hash_sha256" type="string">
    SHA-256 hash
  </ResponseField>

  <ResponseField name="hash_sha512" type="string">
    SHA-512 hash
  </ResponseField>
</ResponseField>

## Repository Links

### Link Package to Repository

Link a package to a repository for better organization.

```bash theme={null}
curl -X POST "https://gitea.example.com/api/v1/packages/{owner}/{type}/{name}/-/link/{repo_name}" \
  -H "Authorization: token YOUR_TOKEN"
```

<ParamField path="repo_name" type="string" required>
  Name of the repository to link to
</ParamField>

### Unlink Package from Repository

Remove the link between a package and a repository.

```bash theme={null}
curl -X POST "https://gitea.example.com/api/v1/packages/{owner}/{type}/{name}/-/unlink" \
  -H "Authorization: token YOUR_TOKEN"
```

## Package Type Specific Examples

### Docker/Container Images

Container images use the standard Docker Registry API v2 protocol.

```bash theme={null}
# Login to registry
docker login gitea.example.com

# Push image
docker tag myapp:latest gitea.example.com/owner/myapp:latest
docker push gitea.example.com/owner/myapp:latest

# Pull image
docker pull gitea.example.com/owner/myapp:latest
```

<Note>
  Container images are accessed at: `gitea.example.com/owner/image:tag`
</Note>

### npm Packages

Publish and install npm packages from Gitea.

```bash theme={null}
# Configure npm registry
npm config set @scope:registry https://gitea.example.com/api/packages/{owner}/npm/

# Login
npm login --registry=https://gitea.example.com/api/packages/{owner}/npm/

# Publish package
npm publish

# Install package
npm install @scope/package-name
```

### Maven Artifacts

Configure Maven to use Gitea as a repository.

```xml theme={null}
<!-- In pom.xml -->
<repositories>
  <repository>
    <id>gitea</id>
    <url>https://gitea.example.com/api/packages/{owner}/maven</url>
  </repository>
</repositories>

<distributionManagement>
  <repository>
    <id>gitea</id>
    <url>https://gitea.example.com/api/packages/{owner}/maven</url>
  </repository>
</distributionManagement>
```

```bash theme={null}
# Deploy to Gitea
mvn deploy
```

### PyPI Packages

Publish Python packages to Gitea.

```bash theme={null}
# Configure pip
pip config set global.index-url https://gitea.example.com/api/packages/{owner}/pypi/simple

# Upload with twine
twine upload --repository-url https://gitea.example.com/api/packages/{owner}/pypi dist/*

# Install package
pip install package-name
```

### NuGet Packages

Manage .NET packages with NuGet.

```bash theme={null}
# Add source
dotnet nuget add source https://gitea.example.com/api/packages/{owner}/nuget/index.json -n gitea

# Push package
dotnet nuget push package.nupkg --source gitea --api-key YOUR_TOKEN

# Install package
dotnet add package PackageName --source gitea
```

### Generic Packages

Upload arbitrary files as generic packages.

```bash theme={null}
# Upload file
curl -X PUT "https://gitea.example.com/api/packages/{owner}/generic/{package_name}/{version}/{filename}" \
  -H "Authorization: token YOUR_TOKEN" \
  -T ./file.tar.gz

# Download file
curl -X GET "https://gitea.example.com/api/packages/{owner}/generic/{package_name}/{version}/{filename}" \
  -H "Authorization: token YOUR_TOKEN" \
  -o downloaded-file.tar.gz
```

### Helm Charts

Manage Kubernetes Helm charts.

```bash theme={null}
# Add repo
helm repo add gitea https://gitea.example.com/api/packages/{owner}/helm

# Push chart
helm cm-push chart.tgz gitea

# Install chart
helm install myrelease gitea/mychart
```

### Cargo Crates

Publish Rust crates to Gitea.

```toml theme={null}
# In .cargo/config.toml
[registries.gitea]
index = "https://gitea.example.com/api/packages/{owner}/cargo/index"

[registry]
default = "gitea"
```

```bash theme={null}
# Publish crate
cargo publish --registry gitea
```

## Package Metadata

Each package type stores specific metadata:

<Tabs>
  <Tab title="npm">
    * Package description
    * Dependencies
    * Keywords
    * License
    * Author information
  </Tab>

  <Tab title="Maven">
    * Group ID
    * Artifact ID
    * Packaging type
    * Dependencies
    * Developers
  </Tab>

  <Tab title="Container">
    * Image manifest
    * Layer digests
    * Config blob
    * Platform information
    * Labels
  </Tab>

  <Tab title="PyPI">
    * Description
    * Requirements
    * Classifiers
    * Project URLs
    * Author information
  </Tab>
</Tabs>

## Authentication

Package registry endpoints support multiple authentication methods:

### Token Authentication

```bash theme={null}
curl -H "Authorization: token YOUR_TOKEN" ...
```

### Basic Authentication

```bash theme={null}
curl -u username:password ...
```

### Package Tool Authentication

Most package managers support credential storage:

```bash theme={null}
# npm
npm login

# Docker
docker login gitea.example.com

# Maven (in settings.xml)
<server>
  <id>gitea</id>
  <username>your-username</username>
  <password>your-token</password>
</server>
```

## Storage and Cleanup

### Package Retention

Administrators can configure automatic cleanup rules:

* Retention days for old versions
* Maximum number of versions to keep
* Pattern-based cleanup rules

### Storage Quotas

Package storage may be limited by:

* Per-user quotas
* Organization quotas
* Global instance limits

## Best Practices

<Tip>
  * Use semantic versioning for your packages
  * Link packages to repositories for better traceability
  * Set up cleanup rules to manage storage costs
  * Use scoped packages for npm to avoid naming conflicts
  * Include comprehensive metadata for better discoverability
</Tip>

<Warning>
  * Deleting packages can break dependent projects
  * Consider using deprecation instead of deletion
  * Always verify checksums when downloading packages
</Warning>

## Package Registry Configuration

Server administrators can configure package registry settings in `app.ini`:

```ini theme={null}
[packages]
ENABLED = true
CHUNKED_UPLOAD_PATH = data/tmp/package-upload
LIMIT_TOTAL_OWNER_SIZE = -1
LIMIT_SIZE_ALPINE = -1
LIMIT_SIZE_CARGO = -1
LIMIT_SIZE_COMPOSER = -1
LIMIT_SIZE_CONAN = -1
LIMIT_SIZE_CONDA = -1
LIMIT_SIZE_CONTAINER = -1
LIMIT_SIZE_DEBIAN = -1
LIMIT_SIZE_GENERIC = -1
LIMIT_SIZE_HELM = -1
LIMIT_SIZE_MAVEN = -1
LIMIT_SIZE_NPM = -1
LIMIT_SIZE_NUGET = -1
LIMIT_SIZE_PYPI = -1
LIMIT_SIZE_RPM = -1
LIMIT_SIZE_RUBYGEMS = -1
LIMIT_SIZE_VAGRANT = -1
```

## Error Handling

Common error responses:

* **404 Not Found**: Package or version doesn't exist
* **409 Conflict**: Package version already exists
* **413 Payload Too Large**: Package exceeds size limits
* **422 Unprocessable Entity**: Invalid package format or metadata
* **403 Forbidden**: Insufficient permissions

## Rate Limiting

Package registry endpoints may be subject to rate limiting to prevent abuse. Check response headers:

* `X-RateLimit-Limit`: Maximum requests per time window
* `X-RateLimit-Remaining`: Remaining requests
* `X-RateLimit-Reset`: Time when limit resets