Deployment and Release

Deployment and Release

How universal-ai-config is packaged and distributed. For maintainers and release managers.

• Repository: https://github.com/DevArtsLab/tool-universal-ai-config
• PyPI name: universal-ai-config (CLI command: ai-config)

Distribution channels

Channel	Install command	Status
PyPI	uv tool install universal-ai-config, pipx install, pip install	Automated on tag
GitHub Releases	Standalone binaries ai-config-<os>-<arch>	Automated on tag
curl installer	curl -fsSL .../install.sh | bash	Uses uv/pipx when present
Homebrew	brew install DevArtsLab/tap/ai-config	Manual

One-time setup: PyPI trusted publishing

The publish workflow uses OIDC trusted publishing, so no API token is needed.

1. Go to https://pypi.org/manage/account/publishing/
2. Add a publisher:
   • Owner: DevArtsLab
   • Repository: tool-universal-ai-config
   • Workflow: publish.yml
   • Environment: pypi
3. In GitHub, create a pypi environment (Settings > Environments > New environment)

Fallback: create a PYPI_API_TOKEN repo secret and pass it to the publish step.

Cutting a release

Everything is driven by git tags:

# 1. Bump version in pyproject.toml
# 2. Commit and push to main
# 3. Tag and push
git tag v0.1.1
git push origin v0.1.1

The tag must match version in pyproject.toml or the workflow fails.

Pushing a v* tag runs .github/workflows/publish.yml, which:

1. Verifies the tag matches pyproject.toml
2. Builds sdist and wheel
3. Publishes to PyPI via trusted publishing
4. Builds PyInstaller binaries: linux-x86_64, macos-x86_64, macos-arm64, windows-x86_64
5. Smoke-tests each binary
6. Creates a GitHub release with the binaries attached

Manual PyPI upload (fallback)

pip install build twine
python -m build
twine upload dist/*

Homebrew tap

Create DevArtsLab/homebrew-tap and add Formula/ai-config.rb:

class AiConfig < Formula
  include Language::Python::Virtualenv

  desc "Unified configuration management for AI agents"
  homepage "https://github.com/DevArtsLab/tool-universal-ai-config"
  url "https://files.pythonhosted.org/packages/source/u/universal-ai-config/universal_ai_config-0.1.1.tar.gz"
  sha256 "REPLACE-WITH-SDIST-SHA256"
  license "MIT"

  depends_on "python@3.13"

  def install
    virtualenv_install_with_resources
  end

  test do
    system bin/"ai-config", "--help"
  end
end

Get the sdist URL and sha256 from the PyPI files page and update them each release.

Release checklist

• PyPI trusted publisher configured (or PYPI_API_TOKEN secret set)
• GitHub pypi environment created
• Tag push triggers publish.yml successfully
• uvx ai-config --help works from PyPI
• Release binaries download and run
• install.sh works on a clean machine (uv, pipx, and bare-python paths)

Security notes

• OIDC trusted publishing avoids long-lived PyPI tokens
• All downloads use HTTPS
• Workflow actions are pinned by major version tag; consider SHA pinning for stricter supply-chain control