Gitea Package Registry Guide

Gitea runs as a package-only registry (git/code features disabled) and is the single home for Docker images, npm packages and NuGet packages. It replaces five legacy services: docker-registry, registry-admin, ProGet, BaGet and Verdaccio.

Source Of TruthCopy Anchor Link

• Stack: swarm/stacks/services/gitea/gitea.yml
• Swarm stack name: service
• Custom template (package-only org menu): swarm/stacks/services/gitea/custom/templates/org/menu.tmpl
• VPS env: runtime/environments/vps/infrastructure/scm/gitea/.env
• Dev template: runtime/environments/dev/infrastructure/scm/gitea/gitea.dev.env
• Secret: gitea_db_password (created by swarm/secrets/create-all-secrets.sh)
• Launcher: swarm/scripts/services/service.{sh,bat}

EndpointsCopy Anchor Link

Everything is served from a single host, gitea.perspective-v.com, and every package is owned by the organization perspective-v.

Unlike the old registry, Docker images must be namespaced under the owner. There is no root-level gitea.perspective-v.com/<image> — always include /perspective-v/.

Authentication tokens (for humans and CI/CD)Copy Anchor Link

Gitea has no separate "feed API keys". A single personal access token authenticates Docker, npm and NuGet. The token is used as the password for Docker/npm/NuGet logins.

Required token scopesCopy Anchor Link

• Push packages: write:package
• Pull packages only: read:package

Option A — generate a token in the web UI (recommended for humans)Copy Anchor Link

1. Sign in at https://gitea.perspective-v.com.
2. Go to Settings → Applications → Manage Access Tokens (/user/settings/applications).
3. Enter a token name (e.g. docker-cli), select the scopes write:package and read:package, click Generate Token.
4. Copy the token immediately — it is shown only once.

Option B — generate a token for a CI user via CLI (recommended for pipelines)Copy Anchor Link

Create a dedicated CI user (so pipeline pushes are not tied to a personal admin account), add it to the org, and mint a scoped token. Run on the VPS:

# 1. get the running gitea container id
CID=$(docker ps --filter name=service_gitea -q | head -1)

# 2. create a CI user (set a strong password)
docker exec -u git "$CID" gitea admin user create \
  --username ci-bot --email ci-bot@perspective-v.com \
  --password '<STRONG_PASSWORD>' --must-change-password=false

# 3. mint a token limited to package read/write
docker exec -u git "$CID" gitea admin user generate-access-token \
  --username ci-bot --scopes write:package,read:package \
  --token-name ci --raw

Then, in the Gitea UI (as an org owner), add ci-bot to the perspective-v organization with a team that can write packages (/org/perspective-v/teams → team → Permissions: Packages = Write).

Use ci-bot + the printed token as the registry username/password in CI.

Docker imagesCopy Anchor Link

# login (token is the password)
echo "<TOKEN>" | docker login gitea.perspective-v.com -u <username> --password-stdin

# tag + push
docker tag myapp:latest gitea.perspective-v.com/perspective-v/myapp:1.0.0
docker push gitea.perspective-v.com/perspective-v/myapp:1.0.0

# pull
docker pull gitea.perspective-v.com/perspective-v/myapp:1.0.0

npm packagesCopy Anchor Link

Packages should be scoped to @perspective-v. Configure a project or user .npmrc:

@perspective-v:registry=https://gitea.perspective-v.com/api/packages/perspective-v/npm/
//gitea.perspective-v.com/api/packages/perspective-v/npm/:_authToken=<TOKEN>

# publish (package.json name must be "@perspective-v/<name>")
npm publish

# install
npm install @perspective-v/<name>

NuGet packagesCopy Anchor Link

# add the source (username = Gitea user, password = TOKEN)
dotnet nuget add source https://gitea.perspective-v.com/api/packages/perspective-v/nuget/index.json \
  --name gitea --username <username> --password <TOKEN> --store-password-in-clear-text

# push
dotnet nuget push MyPackage.1.0.0.nupkg --source gitea --api-key <TOKEN>

# restore / install pulls from the configured source automatically
dotnet restore

The NuGet push endpoint is .../nuget without a trailing slash; dotnet resolves it from the service index automatically, so always point tools at .../nuget/index.json.

CI/CD pipeline configurationCopy Anchor Link

The pipeline templates live in runtime/ci/github-actions/ and runtime/ci/azure-pipelines/. They read the registry host, image namespace and feed URLs/credentials from CI secrets/variables — set these in the GitHub repo (Settings → Secrets and variables → Actions) or Azure (Library / pipeline variables).

The templates already default to:

REGISTRY_HOST: gitea.perspective-v.com
REGISTRY_NAMESPACE: perspective-v

so images are pushed to gitea.perspective-v.com/perspective-v/<IMAGE_NAME>.

Secret values to set (map legacy → Gitea)Copy Anchor Link

The same Gitea token can be reused for REGISTRY_PASSWORD, NPM_FEED_TOKEN and NUGET_FEED_TOKEN. The old npm.perspective-v.com / nuget.perspective-v.com hosts and the BAGET_API_KEY / NPM_FEED_API_KEY feed keys are retired once pipelines point at Gitea.

Notes & limitationsCopy Anchor Link

• Gitea is a git forge with packages attached; the UI cannot be made fully git-less. The org menu is trimmed to Packages / Members / Teams / Settings via a custom template override, and repo/org creation is blocked (MAX_CREATION_LIMIT=0, DEFAULT_ALLOW_CREATE_ORGANIZATION=false), but the Explore link and code/releases repo units cannot be removed.
• Packages appear on the org profile: https://gitea.perspective-v.com/perspective-v/-/packages.
• Access requires sign-in (open registration is disabled); create users via the CLI or an admin.
• The five legacy services (docker-registry, registry-admin, ProGet, BaGet, Verdaccio) have been RETIRED and removed. Their swarm stacks infra-registry and infra-feeds no longer exist, and the old subdomains (registry.perspective-v.com, registry-admin.perspective-v.com, proget.perspective-v.com, nuget.perspective-v.com, npm.perspective-v.com) now 404.
• Deploy/operate the stack with ./swarm/scripts/services/service.sh {show|deploy|ps|logs|rm}.