pkgpulse

pkgpulse is a template-driven package recipe updater with a broad scope:

• one TOML config file
• nvchecker Python API for update detection
• Jinja2 templates with user-defined template and output paths
• actions as plugins, with git, webhook, and exec at the same level

It is aimed at package recipe repositories rather than one packaging format.

Install

python -m pip install pkgpulse

If you prefer uv:

uv tool install pkgpulse

Then verify the CLI is available:

pkgpulse --help

For local development, validation, and hooks in this repository, see CONTRIBUTING.md.

Quick Start

Start from one of the example configs under examples/config/, then run:

pkgpulse check
pkgpulse diff
pkgpulse render

The default config file is pkgpulse.toml.

Reusable CI Templates

Published automation templates are available for common forge CI systems:

• GitHub: poesty/pkgpulse/.github/actions/pkgpulse@main
• Forgejo: https://codeberg.org/poesty/pkgpulse/.forgejo/actions/pkgpulse@main
• GitLab: codeberg.org/poesty/pkgpulse/pkgpulse@main

Outer workflow examples for GitHub Actions, GitLab CI, and Forgejo Actions live under examples/workflows/. They show how to schedule and wrap pkgpulse without inlining the full setup in every pipeline file.

Configuration

[state]
oldver = ".pkgpulse/oldver.json"
newver = ".pkgpulse/newver.json"

[nvchecker]
max_concurrency = 8
tries = 2

[[targets]]
name = "nvchecker-release"
template = "templates/example.recipe.j2"
output = "build/nvchecker-release.txt"

[targets.check]
source = "github"
github = "lilydjwg/nvchecker"
use_max_tag = true

[targets.context]
package_name = "nvchecker"
summary = "Example package rendered by pkgpulse"
homepage = "https://github.com/lilydjwg/nvchecker"
archive_base = "https://github.com/lilydjwg/nvchecker/archive/refs/tags"

[[targets.actions]]
type = "exec"
when = "changed"
command = ["printf", "rendered %s -> %s\\n", "{{ job.name }}", "{{ paths.output }}"]

Additional example configs live under examples/:

• examples/config/pkgpulse.example.toml: render example with an exec action
• examples/config/pkgpulse-webhook-action.example.toml: webhook example for downstream triggers
• examples/config/pkgpulse-git-action.example.toml: commit example with a git action
• examples/config/pkgpulse-strategies.example.toml: multi-target example showing release and latest-commit packaging side by side

Example templates live under examples/templates/.

Template Context

Every target render gets these objects:

• job: target metadata, template path, output path, and user context
• check: latest nvchecker result, including version, old_version, changed, url, revision, gitref
• paths: project root, template path, output path
• context: the raw [targets.context] mapping
• now: current UTC timestamp

The keys from [targets.context] are also merged into the top-level template namespace.

Action Types

• exec
• webhook
• git

Each action supports when = "always" | "changed" | "updated".

Multi-Strategy Layout

pkgpulse models this by defining multiple targets:

• one target can follow tags directly from the upstream git remote
• another target can follow the latest upstream commit with source = "git" and use_commit = true

See examples/config/pkgpulse-strategies.example.toml for a concrete example that renders both a release spec and a git snapshot spec from the same upstream project.

Commands

• pkgpulse check
• pkgpulse render
• pkgpulse diff
• pkgpulse validate
• pkgpulse run

pkgpulse run --dry-run renders in memory and prints diffs without writing files or executing actions.

Workflow Examples

Repository automation examples for GitHub Actions, GitLab CI, and Forgejo Actions live under examples/workflows/. They are optional outer workflow examples around the published reusable templates listed above.