Swarmauri Git Filter GitHub Release

Store artifacts in GitHub Releases.

Overview

swarmauri_gitfilter_gh_release provides the GithubReleaseFilter, a StorageAdapter and GitFilter hybrid that manages Peagen artifacts as assets attached to a GitHub Release. It:

• Connects to the configured organization, repository, and release tag using PyGithub.
• Creates the release on-demand if it does not already exist.
• Normalizes object keys with an optional prefix, exposing the release contents as a virtual directory via root_uri.
• Uploads and replaces release assets atomically, allowing you to store binary artifacts without worrying about duplicates.
• Supports directory workflows with upload_dir, iter_prefix, and download_prefix helpers for batch operations.

Authentication & configuration

The filter authenticates using a GitHub token sourced from your .peagen.toml or the GITHUB_TOKEN environment variable. The token needs permissions to read and write releases in the target repository.

Example .peagen.toml snippet:

[storage.filters.gh_release]
token = "$GITHUB_TOKEN"

You can also set the environment variable directly:

export GITHUB_TOKEN="ghp_..."

Installation

pip

pip install swarmauri_gitfilter_gh_release

uv

curl -Ls https://astral.sh/uv/install.sh | sh
uv pip install swarmauri_gitfilter_gh_release

Poetry

poetry add swarmauri_gitfilter_gh_release

Usage

from swarmauri_gitfilter_gh_release import GithubReleaseFilter

filt = GithubReleaseFilter.from_uri("ghrel://org/repo/tag/artifacts")

print(filt.root_uri)

The example above resolves the release (creating it if necessary) and prints the normalized root URI (ghrel://org/repo/tag/artifacts/).

Managing artifacts

GithubReleaseFilter mirrors GitHub release assets onto local paths. Each method accepts keys relative to the virtual root defined by the release tag and optional prefix:

• upload(key, data) uploads a file-like object and replaces existing assets that share the same key.
• download(key) streams a release asset back as a BytesIO object for inspection or local persistence.
• upload_dir(path, prefix="") walks a directory tree and pushes each file into the release using the provided prefix.
• iter_prefix(prefix) yields keys that start with the supplied prefix, allowing selective sync logic.
• download_prefix(prefix, dest_dir) restores a tree of assets into a target directory on disk.

Combine these helpers to move trained models, prompts, or configuration bundles between local development and persistent release storage while keeping file layouts consistent.

Want to help?

If you want to contribute to swarmauri-sdk, read up on our guidelines for contributing that will help you get started.