github-action-toolkit

A Python library for building powerful GitHub Actions with type safety, rich output formatting, and comprehensive developer tools.

Key Features

  • ✨ Type-safe with full type annotations and modern Python 3.11+ practices

  • 🛡️ Exception taxonomy with specific exception types for better error handling

  • 🔧 Actionable error messages that explain what went wrong and how to fix it

  • 🎯 Scoped environment helpers for temporary environment variables

  • 🚦 Graceful cancellation support with SIGTERM/SIGINT handlers

  • 📚 Comprehensive documentation with examples and best practices

  • 🔒 Security-focused with input validation and secrets masking

  • 🎨 Rich job summaries with tables, code blocks, and templates

Quick Start

from github_action_toolkit import (
    get_user_input,
    set_output,
    info,
    JobSummary,
)

# Get typed input
name = get_user_input('name') or 'World'

# Print messages
info(f'Hello, {name}!')

# Set outputs
set_output('greeting', f'Hello, {name}!')

# Create rich summary
summary = JobSummary()
summary.add_heading('Results', 1)
summary.add_quote(f'Greeted {name} successfully!')
summary.write()

Documentation

Quick Reference

Looking for something specific? Here’s a quick guide:

Console Output:

  • Print Functions - Print messages, warnings, errors, and debug information

  • Annotations - Create file annotations for linting and code review

Workflow Data:

Job Summaries:

Error Handling:

GitHub Integration:

Development:

Why github-action-toolkit?

Building GitHub Actions in Python gives you access to a rich ecosystem of libraries and familiar syntax. This toolkit provides:

  • Simplified API: Easy-to-use functions that abstract GitHub Actions workflow commands

  • Type Safety: Full type annotations help catch errors before runtime

  • Better Testing: Local simulator for testing actions without GitHub

  • Rich Formatting: Create beautiful job summaries with tables, code blocks, and more

  • Error Handling: Structured exceptions with actionable error messages

  • Security: Built-in secrets masking and input validation patterns

Installation

Install via pip:

pip install github-action-toolkit

Or with uv:

uv add github-action-toolkit

Common Use Cases

  • Input/Output Handling: Type-safe input parsing and output setting

  • Logging & Annotations: Rich console output with file annotations

  • Job Summaries: Create formatted summaries with tables and charts

  • GitHub API: Interact with repositories, PRs, and issues

  • Artifacts & Caching: Manage workflow artifacts and caching

  • Git Operations: Clone, commit, push, and manage repositories

  • Error Handling: Structured exceptions with clear error messages

Getting Help