Configuration (YAML)

This page documents the YAML configuration format for config-driven mode.

Overview

The configuration file is a YAML document with the following top-level sections:

version_source (required/per-project) - Version source configuration
spec_manager (required/per-project) - Spec manager configuration
git (optional) - Git user configuration
work_dir (optional) - Working directory for cloning repositories
projects (required) - List of projects to manage

Note

version_source and spec_manager can be specified globally OR per-project. Per-project settings override global settings.

Version Source Configuration

The version source determines where to fetch upstream version information.

Global Configuration

version_source:
  type: anitya  # or: crates_io, pypi
  config:
    token: "your-api-token"  # source-specific config

Types

Anitya

Monitor releases via Anitya Release Monitoring.

version_source:
  type: anitya
  config:
    token: "optional-api-token"

Config options:

token (string, optional): API token for authenticated requests - Provides higher rate limits - Can also be set via ANITYA_API_TOKEN environment variable

Project requirements:

Must specify identifier as Anitya project ID (integer)

crates.io

Fetch versions directly from crates.io sparse index.

version_source:
  type: crates_io
  config: {}

Config options: None

Project requirements:

Must specify identifier as crate name (string)

PyPI

Fetch versions from PyPI JSON API.

version_source:
  type: pypi
  config: {}

Config options: None

Project requirements:

Must specify identifier as package name (string)

Spec Manager Configuration

The spec manager determines how RPM spec files are updated.

Global Configuration

spec_manager:
  type: packit  # or: rust2rpm, pyp2spec
  config: {}

Types

Packit

Update existing spec files using Packit.

spec_manager:
  type: packit
  config: {}

Config options: None

Project requirements:

Must specify upstream_project_url
Must specify upstream_tag_template

Automatic .packit.yaml creation:

If .packit.yaml doesn’t exist, dist-git-manager will automatically create one using the upstream_project_url and upstream_tag_template values.

rust2rpm

Generate specs from crates.io metadata.

spec_manager:
  type: rust2rpm
  config: {}

Config options: None

Project requirements: None beyond standard fields

Prerequisites:

rust2rpm must be installed: dnf install rust2rpm

pyp2spec

Generate specs from PyPI metadata.

spec_manager:
  type: pyp2spec
  config: {}

Config options: None

Project requirements: None beyond standard fields

Prerequisites:

pyp2spec must be installed: dnf install pyp2spec

Git Configuration

Git configuration for commits and pushes.

git:
  user_name: "Dist Git Manager Bot"
  user_email: "distgit-bot@example.com"
  auto_push: false

Fields:

user_name (string, optional): Git user name for commits
user_email (string, optional): Git user email for commits
auto_push (boolean, optional): Whether to automatically push changes (default: false)

Working Directory

work_dir: "/var/lib/dist-git-manager"

Type: string

Default: /tmp/dist-git-manager

Supports tilde (~) expansion. Created automatically if it doesn’t exist. Lock file is created in this directory.

Projects

List of dist-git projects to manage.

projects:
  - name: "htop"
    identifier: 1234
    repo_url: "https://src.fedoraproject.org/rpms/htop.git"
    release_type: "semver"
    default_branch: "rawhide"
    upstream_project_url: "https://github.com/htop-dev/htop"
    upstream_tag_template: "v{version}"

Required Fields

name (string): Project name for logging and directory naming
identifier (string|int): Package identifier (Anitya ID or package name)
repo_url (string): Dist-git repository URL
release_type (string): semver or rolling
default_branch (string): Default branch name (e.g., rawhide, main)

Conditional Fields

For Packit spec manager:

upstream_project_url (string): Upstream repository URL
upstream_tag_template (string): Template for git tags (use {version} placeholder)

Optional Fields

version_source (dict): Override global version source for this project
spec_manager (dict): Override global spec manager for this project

Release Types

semver

For Semantic Versioning (X.Y.Z format):

Creates release-X.Y branches for each series
Updates spec in appropriate release branch
Fast-forward merges when aligned

rolling

For rolling releases:

Updates default branch only
No release branch creation

Complete Examples

Anitya + Packit (Traditional Fedora)

version_source:
  type: anitya
  config:
    token: "your-token"

spec_manager:
  type: packit
  config: {}

git:
  user_name: "Fedora Packager Bot"
  user_email: "packager@example.com"
  auto_push: false

work_dir: "/var/lib/dist-git-manager"

projects:
  - name: "htop"
    identifier: 1234
    repo_url: "https://src.fedoraproject.org/rpms/htop.git"
    release_type: "semver"
    default_branch: "rawhide"
    upstream_project_url: "https://github.com/htop-dev/htop"
    upstream_tag_template: "{version}"

crates.io + rust2rpm (Rust)

version_source:
  type: crates_io

spec_manager:
  type: rust2rpm

git:
  user_name: "Rust Packager Bot"
  user_email: "rust-bot@example.com"
  auto_push: false

work_dir: "/var/lib/dist-git-manager"

projects:
  - name: "serde"
    identifier: "serde"
    repo_url: "https://src.fedoraproject.org/rpms/rust-serde.git"
    release_type: "semver"
    default_branch: "rawhide"

PyPI + pyp2spec (Python)

version_source:
  type: pypi

spec_manager:
  type: pyp2spec

git:
  user_name: "Python Packager Bot"
  user_email: "python-bot@example.com"
  auto_push: false

work_dir: "/var/lib/dist-git-manager"

projects:
  - name: "requests"
    identifier: "requests"
    repo_url: "https://src.fedoraproject.org/rpms/python-requests.git"
    release_type: "semver"
    default_branch: "rawhide"

Mixed Mode

Different projects can use different version sources and spec managers:

# No global version_source or spec_manager

git:
  user_name: "Multi-Language Bot"
  user_email: "bot@example.com"
  auto_push: false

work_dir: "/var/lib/dist-git-manager"

projects:
  # Anitya + Packit
  - name: "htop"
    identifier: 1234
    repo_url: "https://src.fedoraproject.org/rpms/htop.git"
    release_type: "semver"
    default_branch: "rawhide"
    version_source:
      type: anitya
    spec_manager:
      type: packit
    upstream_project_url: "https://github.com/htop-dev/htop"
    upstream_tag_template: "v{version}"

  # crates.io + rust2rpm
  - name: "serde"
    identifier: "serde"
    repo_url: "https://src.fedoraproject.org/rpms/rust-serde.git"
    release_type: "semver"
    default_branch: "rawhide"
    version_source:
      type: crates_io
    spec_manager:
      type: rust2rpm

  # PyPI + pyp2spec
  - name: "requests"
    identifier: "requests"
    repo_url: "https://src.fedoraproject.org/rpms/python-requests.git"
    release_type: "semver"
    default_branch: "rawhide"
    version_source:
      type: pypi
    spec_manager:
      type: pyp2spec

Validation

The tool validates configuration on startup:

projects field must exist and be a list
Each project must have all required fields
Global or per-project version_source must be specified
Global or per-project spec_manager must be specified
release_type must be semver or rolling

If validation fails, the tool exits with an error message.

Best Practices

Start with dry-run: Always test with --dry-run first
Disable auto-push: Keep auto_push: false until confident
Use API tokens: Get better rate limits with Anitya tokens
Persistent work_dir: Use a persistent directory (not /tmp) for production
Test one project: Start with a single project before adding more
Version control: Keep your config.yaml in version control
Separate configs: Use different configs for different package sets

Environment Variables

ANITYA_API_TOKEN: API token for Anitya (overrides config file)

Example:

export ANITYA_API_TOKEN="your-token-here"
dist-git-manager -c config.yaml