GitHub Action Execution Flow

[rexjohannes]

The following outline describes the logical sequence of the GitHub Action from trigger to completion. Components marked as [TODO: Script] represent the custom logic you need to maintain within your Docker container.

1. Event Trigger
   The workflow is initiated by a GitHub event, typically a push to the main branch or the creation of a release tag.
   Context: GitHub provides a temporary GITHUB_TOKEN (for API auth) and environment variables (like the Repo Name and SHA).

2. Environment Setup (Runner)
   Checkout: The repository is cloned. Note: Must use fetch-depth: 2 or 0 to ensure the previous commit is available for comparison.

3. Execution Phase (Inside Docker [TODO])
   The Action runs the container, which executes the entry-point script (the Orchestrator).

Step A: Change Extraction [TODO: Script or already inside the parser?]
The orchestrator runs a Git command (e.g., git diff HEAD~1) to capture the raw code changes between the current and previous state.

Step B: Data Parsing [TODO: Script]
The raw diff is passed to the Parser. This script extracts specific logic, removes boilerplate code, and prepares a clean string for the AI.

Step C: AI Analysis [TODO: Script]
The AI Wrapper sends the parsed data to an LLM (Large Language Model). It uses a prompt (we got that one already) to ask for documentation notes.

Step D: Issue Generation [TODO: Script]
The script then calls the GitHub REST API to create a new Issue in the repository containing the notes.

4. Cleanup
   The Docker container exits.

The GitHub Action runner is decommissioned, and sensitive environment variables (API Keys) are wiped from memory.