Packages API

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

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

owner

string

required

Package owner (username or organization name)

type

string

Filter by package type (npm, maven, container, etc.)

string

Search query to filter packages by name

page

integer

Page number for pagination (default: 1)

limit

integer

Number of items per page (default: 30)

packages

array

integer

Package ID

type

string

Package type

name

string

Package name

version

string

Latest version

creator

object

User who created the package

created_at

string

Creation timestamp

repository

object

Linked repository (if any)

Get Package

Get details about a specific package version.

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

type

string

required

Package type

name

string

required

Package name

version

string

required

Package version

integer

Package version ID

name

string

Package name

version

string

Package version

type

string

Package type

files

array

Files included in this version

metadata

object

Package-specific metadata (varies by type)

Delete Package

Delete a specific package version.

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

Deleting a package version is permanent and cannot be undone.

Package Versions

List Package Versions

List all versions of a specific package.

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

versions

array

List of all versions for the package

Get Latest Version

Get the latest version of a package.

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.

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

files

array

integer

File ID

name

string

Filename

size

integer

File size in bytes

hash_md5

string

MD5 hash

hash_sha256

string

SHA-256 hash

hash_sha512

string

SHA-512 hash

Repository Links

Link Package to Repository

Link a package to a repository for better organization.

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

repo_name

string

required

Name of the repository to link to

Unlink Package from Repository

Remove the link between a package and a repository.

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.

# 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

Container images are accessed at: gitea.example.com/owner/image:tag

npm Packages

Publish and install npm packages from Gitea.

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

<!-- 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>

# Deploy to Gitea
mvn deploy

PyPI Packages

Publish Python packages to Gitea.

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

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

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

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

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

[registry]
default = "gitea"

# Publish crate
cargo publish --registry gitea

Package Metadata

Each package type stores specific metadata:

npm
Maven
Container
PyPI

Package description
Dependencies
Keywords
License
Author information

Authentication

Package registry endpoints support multiple authentication methods:

Token Authentication

curl -H "Authorization: token YOUR_TOKEN" ...

Basic Authentication

curl -u username:password ...

Package Tool Authentication

Most package managers support credential storage:

# 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

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

Deleting packages can break dependent projects
Consider using deprecation instead of deletion
Always verify checksums when downloading packages

Package Registry Configuration

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

[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

Overview

Repositories

Issues & Pull Requests

Organizations & Teams

Users

Actions & Packages

​Overview

​Supported Package Types

​Packages

​List Packages

​Get Package

​Delete Package

​Package Versions

​List Package Versions

​Get Latest Version

​Package Files

​List Package Files

​Repository Links

​Link Package to Repository

​Unlink Package from Repository

​Package Type Specific Examples

​Docker/Container Images

​npm Packages

​Maven Artifacts

​PyPI Packages

​NuGet Packages

​Generic Packages

​Helm Charts

​Cargo Crates

​Package Metadata

​Authentication

​Token Authentication

​Basic Authentication

​Package Tool Authentication

​Storage and Cleanup

​Package Retention

​Storage Quotas

​Best Practices

​Package Registry Configuration

​Error Handling

​Rate Limiting

Build docs developers (and LLMs) love

Overview

Supported Package Types

Packages

List Packages

Get Package

Delete Package

Package Versions

List Package Versions

Get Latest Version

Package Files

List Package Files

Repository Links

Link Package to Repository

Unlink Package from Repository

Package Type Specific Examples

Docker/Container Images

npm Packages

Maven Artifacts

PyPI Packages

NuGet Packages

Generic Packages

Helm Charts

Cargo Crates

Package Metadata

Authentication

Token Authentication

Basic Authentication

Package Tool Authentication

Storage and Cleanup

Package Retention

Storage Quotas

Best Practices

Package Registry Configuration

Error Handling

Rate Limiting