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

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

q · 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

id · 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

id · 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

id · 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

• Package description
• Dependencies
• Keywords
• License
• Author information

Maven

• Group ID
• Artifact ID
• Packaging type
• Dependencies
• Developers

Container

• Image manifest
• Layer digests
• Config blob
• Platform information
• Labels

PyPI

• Description
• Requirements
• Classifiers
• Project URLs
• 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