feat: Added GitHub Actions integration and documentation

[SaptarshiSarkar12]

Fixes #2570

Describe the changes you have made in this PR -

This pull request adds documentation and comprehensive tests for the GitHub Actions integration in OpenSRE. The main changes include new documentation describing the integration's capabilities and configuration, as well as a new test suite that verifies the functionality of the GitHub Actions toolset, including workflow run listing, job/step retrieval, and log extraction.

Demo/Screenshot for feature changes and bug fixes

Demo for opensre onboard:

demo.of.opensre.onboard.mp4

Demo for opensre investigating github actions failed workflow:

recording_new.mp4

Screencast.From.2026-05-29.09-14-49.mp4

Screencast.From.2026-05-29.09-18-05.mp4

---

Code Understanding and AI Usage

Did you use AI assistance (ChatGPT, Claude, Copilot, etc.) to write any part of this code?

• No, I wrote all the code myself
• Yes, I used AI assistance (continue below)

If you used AI assistance:

• I have reviewed every single line of the AI-generated code
• I can explain the purpose and logic of each function/component I added
• I have tested edge cases and understand how the code handles them
• I have modified the AI output to follow this project's coding standards and conventions

Explain your implementation approach:

Currently, opensre is not capable of accessing GitHub Actions workflow details. So, my code implements that feature.
My approach is to use GitHub MCP server to fetch workflow details, and some helper methods normalize the result based on the requirements specified by the input to the tool methods.

An alternative to the GitHub MCP based method is using the GitHub REST APIs. I followed this approach previously, but it has some issues like handling http requests manually, more code for authentication, etc. So, I extended the GitHub MCP code for fetching GitHub Actions workflow details using the call_github_mcp_tool() method.

The key components in my changes are:

• GitHubActionsTool/__init__.py: The file responsible for exposing the tool with typed input schema and normalising the GitHub MCP tool call results.
• test_github_actions_tool.py: This file contains mock tests for the GitHub Actions Tool.
• docs/integrations/github-actions.mdx: Documented usage and examples for the new GitHub Actions Tool.

---

Checklist before requesting a review

• I have added proper PR title and linked to the issue
• I have performed a self-review of my code
• I can explain the purpose of every function, class, and logic block I added
• I understand why my changes work and have tested them thoroughly
• I have considered potential edge cases and how my code handles them
• If it is a core feature, I have added thorough tests
• My code follows the project's style guidelines and conventions

---

Notes to Reviewers

I had two questions two clarify:

• Should I create a separate file for keeping the helper methods?
• For github actions log, only a default of 500 tail lines is fetched and not the complete log. To get the complete log, we need to get the length of log and send a parameter tail_lines with that length. In the response of log content, a parameter original_length is present which tells the length of log text content. Should two requests be made to get the complete log text content? Or should a predefined higher length (like a 1000-line limit) parameter be sent?

Note: Please check Allow edits from maintainers if you would like us to assist in the PR.

[github-actions]

Greptile code review

This repo uses Greptile for automated review. Before merge, aim for Confidence Score: 5/5 with zero unresolved review threads — see CONTRIBUTING.md.

Run a review — add a PR comment with:

@greptile review

Give it ~5-10 minutes (sometimes longer) for results, then fix feedback and re-trigger until you reach Confidence Score: 5/5.

Optional: automate with the greploop skill.

[SaptarshiSarkar12]

@greptile review

[greptile-apps]

Greptile Summary

This PR adds a GitHub Actions integration to OpenSRE, exposing four new tools for listing workflow runs, active runs, job/step outcomes, and fetching step log output — all backed by the GitHub MCP server. It also adds corresponding unit tests and documentation.

• app/tools/GitHubActionsTool/__init__.py: Four @tool-decorated functions that call call_github_mcp_tool, plus log-section extraction helpers to parse ##[group]/##[endgroup] markers from job logs.
• tests/tools/test_github_actions_tool.py: Mock-based tests covering happy paths and edge cases (trailing annotations, ungrouped log lines) for all four tools.
• docs/integrations/github-actions.mdx and docs/docs.json: New documentation page describing configuration and available tools.

Confidence Score: 5/5

Safe to merge; the new tools are additive, well-tested, and the production code paths are straightforward wrappers over the existing GitHub MCP infrastructure.

All four tools follow the established pattern in the codebase, error paths return structured payloads rather than raising, and the test suite covers happy paths and log-parsing edge cases. The two open items (assert statements and step_number indexing) are non-breaking style and edge-case concerns that can be addressed in a follow-up without blocking the feature.

app/tools/GitHubActionsTool/init.py — the assert statements and step_number section-index mismatch are worth a second look before the tool sees heavy agent usage.

Important Files Changed

Filename	Overview
app/tools/GitHubActionsTool/init.py	New file: four @tool-decorated GitHub Actions functions plus log-section parsing helpers. Two assert statements are used for runtime type enforcement in production paths. The step_number fallback in extract_step_log indexes into the full sections list (including ungrouped sections), which may not align with GitHub's 1-based step numbers when preamble content precedes the first group.
tests/tools/test_github_actions_tool.py	New test file covering happy paths and edge cases (trailing annotations, ungrouped sections). Good coverage of the four tools via contract tests and direct mock patches.
docs/integrations/github-actions.mdx	New documentation page describing config, available tools, and an investigation workflow. Accurate and well-structured.
docs/docs.json	Adds the new github-actions.mdx page to the docs navigation.
tests/tools/test_telemetry.py	Registers the four new GitHub Actions tools in the telemetry allowlist for tools without a deliberate catch; no logic changes.

Sequence Diagram

sequenceDiagram
    participant Agent
    participant GitHubActionsTool
    participant _resolve_config
    participant call_github_mcp_tool
    participant GitHub MCP Server

    Agent->>GitHubActionsTool: list_github_actions_workflow_runs(owner, repo, ...)
    GitHubActionsTool->>_resolve_config: github_url, github_mode, github_token
    _resolve_config-->>GitHubActionsTool: "GitHubMCPConfig | None"
    GitHubActionsTool->>call_github_mcp_tool: actions_list / list_workflow_runs
    call_github_mcp_tool->>GitHub MCP Server: HTTP / stdio
    GitHub MCP Server-->>call_github_mcp_tool: {structured_content: {workflow_runs: [...]}}
    call_github_mcp_tool-->>GitHubActionsTool: result dict
    GitHubActionsTool->>GitHubActionsTool: _normalize_run() per item
    GitHubActionsTool-->>Agent: "{available, workflow_runs, total}"

    Agent->>GitHubActionsTool: list_github_actions_active_runs(owner, repo)
    GitHubActionsTool->>call_github_mcp_tool: actions_list / queued
    GitHubActionsTool->>call_github_mcp_tool: actions_list / in_progress
    GitHubActionsTool->>GitHubActionsTool: deduplicate by run_id
    GitHubActionsTool-->>Agent: "{available, workflow_runs, total}"

    Agent->>GitHubActionsTool: get_github_actions_step_log(owner, repo, run_id, job_id)
    GitHubActionsTool->>call_github_mcp_tool: actions_get / get_workflow_job
    GitHub MCP Server-->>call_github_mcp_tool: job metadata + steps
    GitHubActionsTool->>call_github_mcp_tool: "get_job_logs (tail_lines=500)"
    GitHub MCP Server-->>call_github_mcp_tool: raw log text
    GitHubActionsTool->>GitHubActionsTool: "_extract_log_sections() (##[group] parsing)"
    GitHubActionsTool->>GitHubActionsTool: extract_step_log() by step_name or step_number
    GitHubActionsTool-->>Agent: "{step_name, log_text, sections, ungrouped_sections}"

Loading

_{Reviews (5): Last reviewed commit: "fix: fixed formatting issue and improved..." | Re-trigger Greptile}

[greptile-apps]

Greptile Summary

This PR adds a new GitHubActionsTool module that exposes four MCP-backed tools for listing workflow runs, active runs, run jobs, and fetching step logs, along with a matching test suite and documentation page.

• The log-parsing helper _extract_log_sections silently drops any lines that appear outside ##[group]/##[endgroup] markers, which can cause get_github_actions_step_log to return an incomplete excerpt when runtime-emitted error summaries or exit-code lines appear between group boundaries.
• Four private helper functions are imported directly from GitHubSearchCodeTool instead of a shared utilities module, tightly coupling two unrelated tool files — the PR author flagged this concern themselves and the helpers should be extracted.

Confidence Score: 3/5

The new tool module is functionally useful but has a log-parsing correctness issue that could cause silent data loss in the primary diagnostic path.

The _extract_log_sections function drops log lines outside ##[group]/##[endgroup] markers once a group is seen, directly affecting the diagnostic quality of get_github_actions_step_log. The private-import coupling is a maintenance risk, and the duplicate trigger/event field is a minor inconsistency.

app/tools/GitHubActionsTool/init.py warrants another look, specifically the _extract_log_sections function and the shared-helpers import strategy.

Important Files Changed

Filename	Overview
app/tools/GitHubActionsTool/init.py	New GitHub Actions tool with four callable functions; contains a log-parsing bug where lines outside ##[group] markers are silently dropped, a duplicate field in the run normalizer, and tight coupling via private imports from GitHubSearchCodeTool.
tests/tools/test_github_actions_tool.py	New test suite covering happy-path and contract scenarios; no tests for the is_error/unavailable code paths in list_github_actions_active_runs.
docs/integrations/github-actions.mdx	New integration documentation page; complete and accurate.
docs/docs.json	Adds github-actions doc page to the navigation sidebar; one-line change, no issues.

Sequence Diagram

sequenceDiagram
    participant LLM as LLM / Agent
    participant Tool as GitHubActionsTool
    participant MCP as GitHub MCP Server

    LLM->>Tool: list_github_actions_workflow_runs(owner, repo, ...)
    Tool->>MCP: "call_github_mcp_tool(actions_list, method=list_workflow_runs)"
    MCP-->>Tool: structured_content with workflow_runs list
    Tool-->>LLM: "available=true, normalized workflow_runs"

    LLM->>Tool: list_github_actions_run_jobs(owner, repo, run_id)
    Tool->>MCP: "call_github_mcp_tool(actions_list, method=list_workflow_jobs)"
    MCP-->>Tool: structured_content with jobs list
    Tool-->>LLM: "available=true, normalized jobs"

    LLM->>Tool: get_github_actions_step_log(owner, repo, run_id, job_id)
    Tool->>MCP: "call_github_mcp_tool(actions_get, method=get_workflow_job)"
    MCP-->>Tool: job metadata with steps
    Tool->>MCP: "call_github_mcp_tool(get_job_logs, job_id, return_content=true)"
    MCP-->>Tool: raw log text
    Tool-->>LLM: step_name, log_text, truncated flag, section index

Loading

_{Reviews (2): Last reviewed commit: "Merge branch 'Tracer-Cloud:main' into is..." | Re-trigger Greptile}

[muddlebee]

@SaptarshiSarkar12 demo is missing and greptile score 5/5 needed

[SaptarshiSarkar12]

@greptile review

[SaptarshiSarkar12]

@muddlebee I have completed all the reviews. I had two questions to clarify:

1. For fixing the failing tests, I need to add the registered tool names in either _MIGRATED_TOOL_NAMES or _TOOLS_WITHOUT_DELIBERATE_CATCH. Do I need to explicitly handle report_run_error?

2. Regarding this review comment, currently there are many __init__.py files in app/tools/ directory, where private methods have been imported. This issue can be refactored through a new PR, if you would like to.
   Here is the list of tool __init__.py files:

   • opensre/app/tools/GitHubRepositoryTreeTool/__init__.py

     Lines 8 to 13 in 127301b

     	from app.tools.GitHubSearchCodeTool import (
     	_gh_available,
     	_gh_creds,
     	_normalize_tool_result,
     	_resolve_config,
     	)

   • opensre/app/tools/GitHubFileContentsTool/__init__.py

     Lines 8 to 13 in 127301b

     	from app.tools.GitHubSearchCodeTool import (
     	_gh_available,
     	_gh_creds,
     	_normalize_tool_result,
     	_resolve_config,
     	)

   • opensre/app/tools/GitHubCommitsTool/__init__.py

     Lines 8 to 13 in 127301b

     	from app.tools.GitHubSearchCodeTool import (
     	_gh_available,
     	_gh_creds,
     	_normalize_tool_result,
     	_resolve_config,
     	)

[Davidson3556]

Good work @SaptarshiSarkar12
Two things to fix before this can merge:

1. The telemetry test is failing because the four new tools aren't classified. Add them to _TOOLS_WITHOUT_DELIBERATE_CATCH in tests/tools/test_telemetry.py:

   • get_github_actions_step_log
   • list_github_actions_active_runs
   • list_github_actions_run_jobs
   • list_github_actions_workflow_runs

2. The log parser still drops lines outside ##[group] blocks. Your commit says it captures lines before, between, and after groups, but only the "after the last endgroup" case actually works. Lines before the first group and between two groups still get silently lost, and that's usually where the runner setup output and error annotations live.

[SaptarshiSarkar12]

@Davidson3556 Thank you for reviewing the PR. I have made all the required changes. Please review when you're available.

[muddlebee]

@SaptarshiSarkar12 need to see the entire flow from opensre onboard the integration should work here -> all the env needs to be pasted here, then all of it here https://www.opensre.com/docs/integrations-overview#local-integrations

a full e2e demo is needed :)

[muddlebee]

basically the flow should work from CLI, including env setups etc

[SaptarshiSarkar12]

@muddlebee I have attached the opensre onboard demo. I have also fixed the formatting issue causing the CI to fail, and improved the ungrouped log lines by clustering them under ungrouped_sections key in the json tool result. Please check the demo once and review the PR.

[SaptarshiSarkar12]

@greptile review