How github/issue-metrics works
Project type and purpose
• This is an open-source GitHub Action written in Python.
• Purpose: run inside a GitHub Actions workflow (or as a container), query issues/PRs/discussions via the GitHub API, compute a set of temporal and participation metrics, render a report (Markdown or JSON), and post it back to GitHub as an issue.
High-level file-structure analysis
• Top level:
• action.yml (defines inputs/outputs/entrypoint)
• Dockerfile (builds a Python environment)
• Python scripts (auth.py, config.py, search.py, issue_metrics.py, metric modules, writer modules)
• . github/workflows & docs (CI, linting, examples)
• tests (one per module)
• Pattern: a linear pipeline—authenticate, fetch data, compute metrics (plug-in modules), write output.
Key README insights
• Describes supported authentication modes (GitHub App vs PAT).
• Lists available metrics (each implemented in its own module).
• Shows the two-step workflow:
a) ‘Run issue-metrics tool’
b) ‘Create issue’ from the generated file using a separate Action.
Components
a. Main components:
1) GitHub Actions Host (runner VM)
2) Container / Python runtime (built via Dockerfile)
3) Entry point (action.yml → Python CLI invocation)
4) Config loader (config.py reads inputs & env vars)
5) Auth module (auth.py handles App vs PAT)
6) Query module (search.py, discussions.py fetch paginated data via GitHub REST API)
7) Metrics pipeline: individual modules (time_to_first_response.py, time_to_close.py, time_in_label.py, most_active_mentors.py, etc.)
8) Report formatters (json_writer.py, markdown_writer.py + markdown_helpers.py)
9) Output artifact (issue_metrics.md or .json)
10) Issue creation step (peter-evans/create-issue-from-file Action)
11) External service: GitHub REST API
b. Relationships & interactions:
• The runner spins up the container → entrypoint loads config → auth module obtains credentials → query module streams events → each metric module consumes the event stream → writers aggregate results → output file → second Action uses API to create/update the issue.
c. Architectural patterns & principles:
• Modular “plugin” pattern for metrics (one file per metric).
• Separation of concerns: auth, config, data fetch, computation, formatting.
• “Pipeline” data flow.
d. Key technologies/frameworks:
• Python 3.10+, requests or PyGitHub for API calls.
• Docker container for runtime isolation.
• GitHub Actions inputs/outputs via action.yml.
• CI/CD: GitHub workflows for linting, testing, publishing.