Using Gitea or Forgejo as your container registry

• Enable packages
• Log in and push
• Reverse proxy limits
• Pull from deploy servers
• Link packages to repositories
• Storage and cleanup
• Back it up
• CI integration
• Limits

If you already self-host Gitea or Forgejo for Git, you have a container registry too. The built-in package registry supports OCI images, so you can push and pull Docker images without running a separate registry or paying for private image storage.

§Enable packages

Packages are enabled by default in recent versions. Check app.ini:

[packages]
ENABLED = true

The registry is served from the same domain as the web interface, so TLS is already handled by your reverse proxy.

§Log in and push

Create an access token with write:package scope, then:

docker login git.example.com
docker tag api:latest git.example.com/acme/api:1.4.0
docker push git.example.com/acme/api:1.4.0

The image path is domain/owner/image:tag, where the owner is a user or organization.

§Reverse proxy limits

Image layers can be hundreds of megabytes. If pushes fail with 413 errors, raise the request body limit on the proxy, for example client_max_body_size 0; in Nginx. Also raise proxy timeouts for slow uploads.

§Pull from deploy servers

Give deployment servers a token with only read:package scope, ideally from a dedicated bot user. Do not reuse a personal admin token.

§Link packages to repositories

Link each package to its repository in the package settings, so permissions follow the repository and the image appears next to the code.

§Storage and cleanup

Images add up quickly when CI pushes on every commit. Configure cleanup rules per owner: keep the last 10 versions, delete versions older than 30 days, and always keep tags that match a release pattern like ^v\d+.

Package storage lives in the data directory by default. You can move it to S3-compatible storage with the [storage.packages] section if local disk is tight.

§Back it up

Packages are part of the Gitea data directory or object storage. Include them in backups, or decide explicitly that images can be rebuilt from Git tags and exclude them to save space.

§CI integration

Gitea and Forgejo Actions can push images using the built-in token. Keep the build and push in one job so tags match the commit.

§Limits

The built-in registry is simple. It lacks vulnerability scanning and replication. For a small team, that is often acceptable.

For instance sizing, SSH setup and backups, see this guide to self-hosting Gitea or Forgejo.

Disclosure: I work on Peon.