Skip to content

Commit 633fc81

Browse files
arikalon1claude
arikalon1
and
claude
authored
Add HolmesGPT GitHub Actions integration documentation (#2051)
* Add docs for HolmesGPT PR review GitHub Action Adds a new "GitHub Actions" section to the docs sidebar, next to "HTTP APIs", documenting the HolmesGPT PR review action: prerequisites, Robusta API key and cluster setup, required GitHub secrets, the workflow file, and troubleshooting. https://claude.ai/code/session_01KKnLu24WBHBc4SjbpxPrMM * update docs --------- Co-authored-by: Claude <noreply@anthropic.com>
1 parent 1e3123e commit 633fc81

5 files changed

Lines changed: 157 additions & 0 deletions

File tree

‎docs/configuration/github-actions/holmes-pr-review.rst‎

Lines changed: 137 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,137 @@
1+
HolmesGPT PR Review
2+
===================
3+
4+
.. note::
5+
This integration is available with the Robusta SaaS platform and self-hosted commercial plans. It is not available in the open-source version.
6+
7+
Use HolmesGPT as a GitHub Action to automatically review pull requests. On every PR open, reopen, or push, the action asks HolmesGPT to review the change and post its review as a comment on the pull request. You control what Holmes checks by editing the prompt — it can flag risky changes, check code against runbooks, cross-reference logs or metrics, or run any investigation available via its :doc:`data sources <../holmesgpt/main-features>`.
8+
9+
Example review posted by HolmesGPT on a pull request:
10+
11+
.. image:: /images/holmes-pr-review-example.png
12+
:width: 700
13+
:align: center
14+
15+
How It Works
16+
------------
17+
18+
1. A pull request event triggers the GitHub Action.
19+
2. The action calls the :ref:`Holmes Chat API <holmes-chat-api>` with your review prompt and the PR URL.
20+
3. HolmesGPT uses the GitHub toolset to read the pull request, reason about it using the data sources you have configured, and post its review as a comment on the PR.
21+
22+
Prerequisites
23+
-------------
24+
25+
Before setting up the action, you must enable the Holmes GitHub integration so HolmesGPT can read pull requests and post comments. Follow the `HolmesGPT GitHub toolset guide <https://holmesgpt.dev/latest/data-sources/builtin-toolsets/github-mcp/>`_.
26+
27+
Setup
28+
-----
29+
30+
Step 1: Create a Robusta API Key
31+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
32+
33+
In the Robusta Platform, navigate to **Settings** → **API Keys** and click **New API Key**.
34+
35+
Give the key a descriptive name (for example, ``HolmesGPT github action``) and check the **Robusta AI Write** capability. Click **Generate API Key** and copy the key — you will not be able to view it again.
36+
37+
.. image:: /images/new-api-key.png
38+
:width: 600
39+
:align: center
40+
41+
Step 2: Get Your Account ID and Cluster ID
42+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
43+
44+
In the Robusta Platform, navigate to **Settings** → **Workspace** and copy your **Account ID**.
45+
46+
Then pick the cluster HolmesGPT should run the investigation on and copy its **Cluster ID**. Any cluster connected to your account can be used — HolmesGPT will use its data sources (logs, metrics, Kubernetes state, etc.) from that cluster when reviewing the PR.
47+
48+
Step 3: Add GitHub Secrets
49+
^^^^^^^^^^^^^^^^^^^^^^^^^^
50+
51+
In your GitHub repository, go to **Settings** → **Secrets and variables** → **Actions** and add the following repository secrets:
52+
53+
.. list-table::
54+
:widths: 25 75
55+
:header-rows: 1
56+
:width: 100%
57+
58+
* - Secret
59+
- Value
60+
* - ``ROBUSTA_API_KEY``
61+
- The API key you generated in Step 1.
62+
* - ``ROBUSTA_ACCOUNT_ID``
63+
- The account ID from Step 2.
64+
* - ``ROBUSTA_CLUSTER_ID``
65+
- The cluster ID from Step 2.
66+
67+
Step 4: Add the Workflow File
68+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
69+
70+
Create a new file in your repository at ``.github/workflows/holmes-pr-review.yaml`` with the following contents:
71+
72+
.. code-block:: yaml
73+
74+
name: Holmes PR review
75+
on:
76+
pull_request:
77+
types: [opened, synchronize, reopened]
78+
jobs:
79+
review:
80+
runs-on: ubuntu-latest
81+
env:
82+
RELAY_BASE_URL: https://api.robusta.dev
83+
ACCOUNT_ID: ${{ secrets.ROBUSTA_ACCOUNT_ID }}
84+
API_KEY: ${{ secrets.ROBUSTA_API_KEY }}
85+
CLUSTER_ID: ${{ secrets.ROBUSTA_CLUSTER_ID }}
86+
PR_URL: ${{ github.event.pull_request.html_url }}
87+
PROMPT: |
88+
Review the pull request at the URL below. Flag risky, unclear, or
89+
incomplete changes. You MUST post your review as a single PR comment
90+
on that pull request using your GitHub toolset. Do not reply with the
91+
review in chat only — posting the comment is required.
92+
steps:
93+
- name: Ask Holmes (Holmes posts the comment)
94+
run: |
95+
set -euo pipefail
96+
jq -n \
97+
--arg ask "$PROMPT"$'\n\nPull request: '"$PR_URL" \
98+
--arg cluster "$CLUSTER_ID" \
99+
'{ask: $ask, cluster_id: $cluster, stream: false}' > body.json
100+
curl -fsS --retry 2 \
101+
-H "Authorization: Bearer $API_KEY" \
102+
-H "Content-Type: application/json" \
103+
--data-binary @body.json \
104+
"$RELAY_BASE_URL/api/holmes/$ACCOUNT_ID/chat" > response.json
105+
# Log analysis for debugging; Holmes is expected to have posted the comment.
106+
jq -r '.analysis // "(no analysis text returned)"' response.json
107+
108+
Commit and push the workflow file. The next pull request opened against the repository will trigger the action, and HolmesGPT will post its review as a PR comment.
109+
110+
Customizing the Review Prompt
111+
-----------------------------
112+
113+
The ``PROMPT`` environment variable controls what HolmesGPT checks. Edit it to match your team's review policy. For example:
114+
115+
* Enforce coding standards or architecture rules.
116+
* Cross-reference the change against runbooks, incident history, or documentation in Confluence/Notion.
117+
* Validate that related Kubernetes manifests, Helm values, or Prometheus alert rules are consistent with the code changes.
118+
* Require that PRs changing specific paths include tests.
119+
120+
Whatever you put in the prompt, keep the instruction to post the review as a PR comment — otherwise Holmes will return the review only in the API response.
121+
122+
Configuration Reference
123+
-----------------------
124+
125+
The action calls the :ref:`Holmes Chat API <holmes-chat-api>`. Any parameter supported by that endpoint (for example, ``model`` or ``additional_system_prompt``) can be added to the JSON body in the workflow.
126+
127+
Troubleshooting
128+
---------------
129+
130+
No comment appears on the PR
131+
Check the action logs. The final step prints the ``analysis`` field returned by the API — if it contains a review but no comment was posted, the GitHub integration is not enabled for HolmesGPT. Re-check the `GitHub toolset guide <https://holmesgpt.dev/latest/data-sources/builtin-toolsets/github-mcp/>`_.
132+
133+
``401 Unauthorized``
134+
The ``ROBUSTA_API_KEY`` secret is missing, invalid, or lacks the **Robusta AI Write** capability. Regenerate the key in the Robusta Platform.
135+
136+
``404 Not Found`` or cluster errors
137+
The ``ROBUSTA_CLUSTER_ID`` secret does not match a cluster connected to your account. Copy the cluster ID from the Robusta Platform again.

‎docs/configuration/github-actions/index.rst‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
GitHub Actions
2+
==============
3+
4+
.. note::
5+
These integrations are available with the Robusta SaaS platform and self-hosted commercial plans. They are not available in the open-source version.
6+
7+
Run HolmesGPT inside your GitHub workflows to automate code review and investigation directly from GitHub events.
8+
9+
Available Actions
10+
-----------------
11+
12+
* :doc:`HolmesGPT PR Review <holmes-pr-review>`: Automatically review pull requests with HolmesGPT and post the review as a PR comment.

‎docs/images/holmes-pr-review-example.png‎

173 KB
Loading

‎docs/images/new-api-key.png‎

174 KB
Loading

‎docs/index.rst‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,14 @@
2929
configuration/exporting/alert-statistics-api
3030
configuration/exporting/rbac-api
3131

32+
.. toctree::
33+
:maxdepth: 4
34+
:caption: GitHub Actions
35+
:hidden:
36+
37+
Overview <configuration/github-actions/index>
38+
HolmesGPT PR Review <configuration/github-actions/holmes-pr-review>
39+
3240
.. toctree::
3341
:maxdepth: 4
3442
:caption: Robusta Classic

0 commit comments

Comments
 (0)