Skip to content

Getting Started

Requirements

  • Python 3.13+
  • A running Gitea instance with the package registry enabled
  • A running Devpi server with a user and index already created

Installation

Install from PyPI:

pip install devpi-gitea-sync

Or install from source with Poetry:

git clone https://github.com/veloslab/python-devpi-gitea-sync
cd python-devpi-gitea-sync
poetry install

Creating a configuration file

Create a file named devpi-gitea-sync.conf in your working directory. The minimal configuration requires a Gitea URL and token, a Devpi URL and credentials, and at least one [mapping:name] section linking a Gitea organization to a Devpi index.

[gitea]
url = https://gitea.example.com
token_env = GITEA_TOKEN          # name of an environment variable holding your token

[devpi]
url = https://devpi.example.com
username = devpi-user
password_env = DEVPI_PASSWORD    # name of an environment variable holding your password

[mapping:my-org]
organization = my-org
index = user/dev

Secure the file

The CLI refuses to start if the config file is readable by group or world:

chmod 600 devpi-gitea-sync.conf

Set environment variables

export GITEA_TOKEN=your-gitea-personal-access-token
export DEVPI_PASSWORD=your-devpi-password

Running the tool

Starts a background sync loop and a web dashboard at http://localhost:8080/:

devpi-gitea-sync --server -v

Open http://localhost:8080/ to see which packages are synced and which are pending. The /health endpoint returns a JSON status report suitable for uptime monitoring.

The server polls Gitea every 5 minutes by default. Override this in [runtime]:

[runtime]
poll_interval_seconds = 120

One-off sync

Run a single sync pass and exit — useful for testing or scheduled jobs:

devpi-gitea-sync -v

Dry run

Discover what would be synced without downloading or uploading anything:

devpi-gitea-sync --dry-run -v

Verifying your setup

A dry run with -vv (debug verbosity) shows every API call and decision:

devpi-gitea-sync --dry-run -vv

If you have multiple organizations or mappings configured, scope the run to one:

devpi-gitea-sync --org my-org --dry-run -vv

Next steps