Configuration Reference

The configuration file uses standard INI format (key = value). The default filename is devpi-gitea-sync.conf in the working directory; override with --config path/to/file.conf.

On Linux/macOS the file must have permissions 600 — the CLI refuses to start otherwise.

Sections overview

Section	Required	Purpose
`[gitea]`	Yes	Gitea instance URL and default token
`[gitea:<org>]`	No	Per-organization token override
`[devpi]`	Yes	Default Devpi server
`[devpi:<name>]`	No	Additional named Devpi servers
`[mapping:<name>]`	Yes (≥1)	Links a Gitea org to a Devpi index
`[runtime]`	No	Operational overrides (poll interval, ports, etc.)

`[gitea]`

Option	Type	Default	Description
`url`	string	required	Base URL of the Gitea instance
`token`	string	—	Personal access token (fallback for all orgs)
`token_env`	string	—	Name of env var containing the token
`verify_ssl`	bool or path	`true`	`true`, `false`, or a path to a CA bundle
`timeout`	float	`10`	HTTP request timeout in seconds

Supply either token (value in the file) or token_env (name of an environment variable), not both.

`[gitea:<org>]`

Overrides the Gitea token for a specific organization. The URL is always taken from [gitea]; only the token is overridden.

Option	Type	Description
`token`	string	Token for this org
`token_env`	string	Name of env var containing the token

At least one of token or token_env is required in this section.

Example — two orgs, separate tokens:

[gitea]
url = https://gitea.example.com

[gitea:team-alpha]
token_env = GITEA_TOKEN_ALPHA

[gitea:team-beta]
token_env = GITEA_TOKEN_BETA

`[devpi]` and `[devpi:<name>]`

[devpi] is the default server used by any mapping that does not specify devpi = .... Additional named servers use [devpi:<name>] with the same options.

Option	Type	Default	Description
`url`	string	required	Base URL of the Devpi server
`username`	string	required	Devpi username
`password`	string	—	Password (mutually exclusive with `token`)
`password_env`	string	—	Name of env var containing the password
`token`	string	—	Auth token (mutually exclusive with `password`)
`token_env`	string	—	Name of env var containing the token
`verify_ssl`	bool or path	`true`	`true`, `false`, or a path to a CA bundle
`timeout`	float	`30`	HTTP request timeout in seconds

Warning

password and token are mutually exclusive. Specifying both raises a configuration error at startup.

`[mapping:<name>]`

Each mapping links one Gitea organization to one Devpi index. Define as many as needed.

Option	Type	Default	Description
`organization`	string	section name	Gitea organization to sync from
`index`	string	required	Devpi index in `user/index` format
`devpi`	string	`default`	Name of the Devpi server to target
`token`	string	—	Per-mapping Gitea token (overrides org and global)
`token_env`	string	—	Name of env var containing the token
`repositories`	string	—	Comma-separated allowlist of repository names
`include_archived`	bool	`false`	Whether to include archived repositories

Token resolution order

For each mapping, the Gitea token is resolved with the first match winning:

[mapping:<name>] token / token_env     (most specific)
        │  not set?
        ▼
[gitea:<organization>] token / token_env
        │  not set?
        ▼
[gitea] token / token_env              (global default)
        │  not set?
        ▼
    error — mapping is skipped

Repository allowlist

When repositories is set, only packages whose source repository matches are synced:

[mapping:selected]
organization = my-org
index = user/dev
repositories = core-lib, data-utils, api-client

Matching is case-insensitive. Both short names (repo-name) and full names (org/repo-name) are accepted.

`[runtime]`

Optional section for operational overrides.

Option	Type	Default	Description
`poll_interval_seconds`	int	`300`	Seconds between syncs in server mode (minimum: 60)
`download_dir`	path	system temp	Directory used to stage downloads before uploading
`server_host`	string	`0.0.0.0`	Host address the web server binds to
`server_port`	int	`8080`	Port the web server listens on

Full example

[gitea]
url = https://gitea.example.com
token_env = GITEA_ROOT_TOKEN

[gitea:team-beta]
token_env = GITEA_TOKEN_BETA

[devpi]
url = https://devpi.example.com
username = devpi-user
password_env = DEVPI_PASSWORD

[devpi:prod]
url = https://prod.devpi.example.com
username = devpi-prod
token_env = DEVPI_PROD_TOKEN

[mapping:team-alpha]
organization = team-alpha
index = shared/packages

[mapping:team-beta]
organization = team-beta
index = shared/packages
repositories = core-lib, data-utils

[mapping:my-org-prod]
organization = my-org
devpi = prod
index = user/stable

[runtime]
poll_interval_seconds = 120
server_host = 127.0.0.1
server_port = 9090

Command-line options

Command-line flags override their equivalent config-file settings.

Flag	Description
`-c / --config PATH`	Path to the config file
`-o / --org ORG`	Limit sync to a specific Gitea organization (repeatable)
`-m / --mapping NAME`	Limit sync to a specific mapping name (repeatable)
`--dry-run`	Discover packages without downloading or uploading
`--force`	Re-upload packages even when the version already exists in Devpi
`--server`	Start server mode with the web dashboard
`--host HOST`	Web server bind address (overrides `[runtime] server_host`)
`--port PORT`	Web server port (overrides `[runtime] server_port`)
`-v / --verbose`	Increase log verbosity; `-vv` for debug