GitHub Issues Integration
Relevant source files
The following files were used as context for generating this wiki page:
The GitHub Issues Integration is a core feature of Morty that allows the autonomous AI coding loop to treat GitHub issues as a primary task source. Instead of relying on local Markdown or YAML files, Morty can pull open issues from a specified repository, use their descriptions as prompts for the AI, and automatically close them upon successful task completion.
This integration bridges the gap between project management and autonomous execution, enabling a workflow where issues labeled for AI intervention are automatically picked up and implemented by the agent.
Sources: cli/src/tasks/github.ts:6-9, morty.sh:588-601, README.md:104-107
Architecture and Components
The integration is built around the GitHubTaskSource class, which implements the standard TaskSource interface. This allows the GitHub integration to be used interchangeably with other sources like local Markdown files or folders.
GitHubTaskSource Class
The implementation utilizes the @octokit/rest library to communicate with the GitHub API. It handles authentication via environment variables and manages the translation between GitHub Issue objects and Morty's internal Task structure.
The GitHubTaskSource constructor parses a repository path string (e.g., owner/repo) and optionally accepts a label to filter tasks.
Sources: cli/src/tasks/github.ts:6-28, cli/src/config/types.ts:98-100
Data Flow and Execution
When GitHub is selected as the task source, the application follows a specific sequence to fetch, process, and finalize tasks.
Task Retrieval and Processing
The system retrieves open issues and maps them to a consistent internal format. Each task ID is prefixed with the issue number (e.g., 123:Title) to ensure accurate tracking throughout the execution loop.
Automated Completion
Unlike local files where the AI agent is instructed to modify the file (e.g., changing - [ ] to - [x]), GitHub issues are closed programmatically by the Morty runtime after the implementation phase is verified.
| Action | Logic | Implementation Reference |
|---|---|---|
| Parsing ID | Extracts issue number from the number:title string format. | cli/src/tasks/github.ts:58-63 |
| Closing Issue | Calls GitHub API to set issue state to closed. | cli/src/tasks/github.ts:65-70 |
| Status Sync | Updates local progress log with completion status. | morty.sh:1010-1013 |
Sources: cli/src/tasks/github.ts:57-71, morty.sh:1010-1013
Configuration and Usage
The integration can be triggered via CLI flags or configured within the .morty/config.yaml file.
CLI Parameters
| Flag | Description | Default |
|---|---|---|
--github <repo> | The target repository in owner/repo format. | N/A |
--github-label <tag> | Optional label to filter specific issues (e.g., "ai-ready"). | Empty |
Sources: cli/src/cli/args.ts:39-40, morty.sh:417-424
Environment Requirements
To operate, the integration requires the GITHUB_TOKEN environment variable to be set. This token must have permissions to read issues and update issue states within the target repository.
Sources: cli/src/tasks/github.ts:27-29, README.md:195-198
Prompt Injection
When using GitHub issues, Morty specifically modifies the prompt sent to the AI engine. It injects the Issue Description (the body of the GitHub issue) into the context to ensure the AI has full detail on the requirements beyond just the issue title.
Sources: morty.sh:642-650, cli/src/tasks/github.ts:100-116
Summary
The GitHub Issues Integration transforms Morty into a remote-task-driven agent. By implementing the GitHubTaskSource, Morty can autonomously fetch work from a central repository, utilize issue bodies for implementation context, and update the repository state by closing issues upon success. This allows teams to manage AI coding tasks through standard GitHub project management workflows.