AutoPR

Processes GitHub events (issues, PRs, pushes) through a TriggerService that matches events against defined triggers, then orchestrates multi-step workflows via WorkflowService. Uses a service-oriented architecture where MainService initializes core services (TriggerService, WorkflowService, ActionService, PlatformService) and coordinates event-to-workflow routing. Workflows are defined in YAML and executed sequentially with context passed between steps.

Defines workflows as YAML files containing sequential steps that execute actions with input/output binding. Each step receives a context object containing results from previous steps, allowing data flow between actions. WorkflowService parses YAML, instantiates steps, and threads context through execution. Supports variable interpolation using {{ }} syntax to reference previous step outputs or GitHub event metadata.

Workflows have access to rich repository context including current branch, commit SHA, file structure, and GitHub event metadata. This context is passed through the execution pipeline and available to actions via the context object. Actions can query repository state (list files, read file contents, get commit history) to make decisions and generate contextual outputs. The system maintains a unified context object that accumulates results from previous steps.

Workflows are composed of sequential steps, each executing an action with input parameters and capturing output. WorkflowService manages step execution, input validation, and output formatting. Steps can reference outputs from previous steps using {{ step_name.output_field }} syntax. If a step fails, the workflow halts and an error is logged. Each step is isolated; failures in one step do not affect others, but they prevent subsequent steps from executing.

AutoPR can be deployed as a GitHub Action via action.yml, enabling it to run within GitHub Actions workflows. The gh_actions_entrypoint.py script handles GitHub Actions-specific setup (environment variables, input parsing, output formatting). This allows AutoPR workflows to be triggered by GitHub Actions events and integrated into existing CI/CD pipelines. The system can be invoked on push, pull_request, issue, or schedule triggers.

ActionService discovers, instantiates, and executes actions defined as Python classes inheriting from a base Action interface. Actions are located via a registry pattern (scanning autopr/actions/ directory) and instantiated with input parameters from workflow steps. Each action encapsulates a discrete AI-powered capability (code generation, documentation, analysis) and returns structured output. The framework handles input validation, execution, and output formatting.

CommitService handles Git operations (branch creation, staging, committing, pushing) while PublishService manages PR creation and updates. Actions modify files in the working directory, CommitService commits changes to a feature branch, and PublishService creates or updates a PR with formatted descriptions. The system tracks which files were modified and generates PR descriptions based on changes. Uses Git CLI under the hood for all operations.

AutoPR ships with predefined workflows for common tasks: README generation (analyzing codebase and updating documentation), TODO detection (finding TODO comments and creating GitHub issues), and API Git history (recording API call results). These workflows are implemented as YAML templates in autopr/workflows/ and can be triggered by specific GitHub events. Templates demonstrate the workflow composition pattern and serve as starting points for custom workflows.

The FindTodos action scans repository files for TODO comments using regex patterns, extracts the comment text and file location, and returns structured data. It recursively traverses the codebase, filters by file type (skipping binaries and common non-source files), and normalizes TODO formats. Output includes file path, line number, and TODO text, which can be used to create GitHub issues or generate reports.

CacheService uses SQLite databases (.autopr/cache/choice.db, .autopr/cache/prompt.db) to cache action results and LLM responses. Actions can opt-in to caching by storing results with a cache key. On subsequent runs, if the same action is invoked with identical inputs, the cached result is returned instead of re-executing. This reduces API calls and improves workflow performance for deterministic actions.

PlatformService is an abstract interface for interacting with version control platforms, with GitHubPlatformService providing concrete GitHub API implementations. The abstraction enables workflows to be platform-agnostic; swapping GitHubPlatformService for a GitLabPlatformService would allow the same workflows to run on GitLab. PlatformService handles PR creation/updates, comment publishing, branch operations, and file access through a unified interface.

Actions can generate PR descriptions by analyzing code changes, commit messages, and repository context using LLM prompts. The PublishService formats these descriptions and publishes them to GitHub PRs. Actions can also summarize changes in natural language, extract key modifications, and generate release notes. This capability integrates with the commit workflow to automatically document what changed and why.

TriggerService matches incoming GitHub events against defined triggers in the workflow configuration. Each trigger specifies an event type (issue, pull_request, push) and optional filters (action, label, branch). When an event matches a trigger, the associated workflow is queued for execution. The system supports multiple triggers per workflow and multiple workflows per event type, enabling complex automation routing.