Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
104 changes: 100 additions & 4 deletions docs/content/how-to/ci/ai-assisted-ci-jobs.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,13 +10,14 @@ This document describes the AI-assisted CI jobs that help automate issue resolut

## Overview

HyperShift uses two AI-assisted CI jobs powered by Claude Code to help with development workflows:
HyperShift uses AI-assisted CI jobs powered by Claude Code to help with development workflows:

| Job | Purpose | Schedule |
|-----|---------|----------|
| `periodic-jira-agent` | Analyzes Jira issues and creates draft PRs with fixes | Weekly on Mondays at 8:30 AM UTC |
| `periodic-review-agent` | Addresses PR review comments on agent-created PRs | Every 3 hours (8:00-23:00 UTC) daily |
| `address-review-comments` | On-demand job to address review comments on a single PR | Triggered via `/test address-review-comments` |
| `periodic-hypershift-dependabot-triage` | Consolidates open dependabot PRs into a single weekly PR | Weekly on Fridays at 12:00 UTC |

### Usage Scope

Expand Down Expand Up @@ -210,6 +211,100 @@ flowchart TD

---

## Dependabot Triage Agent

### Overview

The Dependabot Triage Agent (`periodic-hypershift-dependabot-triage`) automatically consolidates open dependabot PRs into a single weekly pull request, reducing noise and simplifying dependency updates.

- **Job name**: `periodic-hypershift-dependabot-triage`
- **Schedule**: Weekly on Fridays at 12:00 UTC (`0 12 * * 5`)
- **Process timeout**: 2 hours
- **Max agentic turns**: 100
- **Jira**: [CNTRLPLANE-2588](https://issues.redhat.com/browse/CNTRLPLANE-2588)
- **Prow config PR**: [openshift/release#73790](https://github.com/openshift/release/pull/73790)

Comment on lines +224 to +226

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# Description: Verify that the referenced Prow config PR exists

gh pr view 73790 --repo openshift/release --json title,state,url

Repository: openshift/hypershift

Length of output: 162


🌐 Web query:

openshift/release pull request 73790 Prow config CNTRLPLANE-2588

💡 Result:

I wasn’t able to retrieve any public data for openshift/release PR #73790 (or the string CNTRLPLANE-2588) from the OpenShift CI endpoints, and fetching the PR directly from GitHub consistently timed out from this environment—so I can’t confirm what Prow config change (if any) it contains.

What you can use to verify quickly on your side:

  • Prow PR history (job grid) URL format (replace 73790 if needed):
    https://prow.ci.openshift.org/pr-history?org=openshift&repo=release&pr=73790  [1][2]
  • If that page loads, it will show every presubmit/rehearsal job run for the PR and link back to the PR and job artifacts. [2]

If you paste the PR link (or the PR title / author / target branch), I can try again and summarize exactly what the PR changes in Prow config and how it relates to CNTRLPLANE-2588.

Sources
[1] OpenShift CI Docs — Useful Links (prow.ci.openshift.org) (docs.ci.openshift.org)
[2] OpenShift CI Docs — Viewing job artifacts / PR History (docs.ci.openshift.org)

Citations:


🌐 Web query:

CNTRLPLANE-2588 Jira Red Hat Control Plane

💡 Result:

CNTRLPLANE-2588 is a Jira issue key in Red Hat’s CNTRLPLANE project (project name: Red Hat OpenShift Control Planes), used by OpenShift teams to track features/epics/stories/tasks across control-plane workstreams (e.g., HyperShift and related areas). [1]

I couldn’t find any publicly viewable page or details for CNTRLPLANE-2588 via open web search, which usually means the issue is restricted (commonly to Red Hat employees or authenticated users). Red Hat notes that some Jira content is public, but access to other content requires logging in with an appropriate account. [2]

How to proceed:

  • If you’re a customer/partner: ensure you have a Red Hat Customer Portal account, then use it to log into Red Hat Jira and try searching the issue key. [2][3]
  • If you’re a Red Hat employee: log in via Red Hat SSO and open the issue directly in Jira. [2]

Sources: [1] [2] [3]


External references require Red Hat authentication and may not be accessible to all documentation readers.

The Jira ticket CNTRLPLANE-2588 is restricted to authenticated Red Hat users and is not publicly viewable. The GitHub PR openshift/release#73790 could not be verified as publicly accessible. If these are internal references, add a note indicating they require Red Hat access; otherwise, provide publicly accessible alternatives or additional context so readers are not blocked.

🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@docs/content/how-to/ci/ai-assisted-ci-jobs.md` around lines 224 - 226, The
external references (Jira CNTRLPLANE-2588 and GitHub PR openshift/release#73790)
may be behind Red Hat authentication; update the documentation block that lists
these references to indicate they require Red Hat access (e.g., add “(requires
Red Hat authentication)” or similar after each reference), and if possible
supply publicly accessible alternatives or a brief summary of the referenced
content so readers without access aren’t blocked; edit the same lines where the
two references appear to append the access note and/or add an accessible link or
short description.

### How It Works

1. **Setup**: Verifies Claude Code CLI availability
2. **PR Discovery**: Queries all open dependabot PRs via `gh pr list` on the `openshift/hypershift` repository
3. **Filtering**: Excludes PRs that bump `k8s.io` or `sigs.k8s.io` dependencies (these are managed manually as part of coordinated Kubernetes rebases)
4. **Processing**: Invokes Claude Code to process each PR individually:
- Cherry-picks commits onto a consolidation branch
- Runs `make verify` and `make test` after each PR
- Resets and skips any PR that fails validation
5. **Commit Reorganization** (deterministic bash, not LLM): Flattens all cherry-pick commits via `git reset` and reorganizes into logical groups:
1. Root `go.mod`/`go.sum`
2. Root `vendor/`
3. `api/go.mod`/`api/go.sum`
4. `api/vendor/`
5. `hack/tools/go.mod`/`hack/tools/go.sum`
6. `hack/tools/vendor/`
7. Regenerated CRD assets (`cmd/install/assets/`)
8. Remaining generated files
Empty groups are skipped automatically.
6. **Final Validation**: Runs two-pass `make verify` and `make test` on the consolidated branch
7. **Output**: Creates a single consolidated PR from `hypershift-community:fix/weekly-dependabot-consolidation` to `openshift/hypershift`
8. **Reporting**: Generates an HTML report with token usage, cost breakdown, and detailed output

### Data Flow

```mermaid
flowchart TD
subgraph "Prow CI Environment"
A[Periodic Job Trigger<br/>Weekly Friday 12:00 UTC] --> B[Setup Step]
B --> C[Process Step]
C --> D[Report Step]

subgraph "Process Step"
C --> E[Generate GitHub App Tokens]
E --> F[Clone Fork<br/>hypershift-community/hypershift]
F --> G[Query Open Dependabot PRs]
G --> H{PRs Found?}
H -->|No| I[Exit Successfully]
H -->|Yes| J[Filter Out k8s.io Bumps]
J --> K[For Each PR]
K --> L[Cherry-pick + Validate<br/>make verify & make test]
L --> M{Passed?}
M -->|Yes| N[Keep on Branch]
M -->|No| O[Reset & Skip]
N --> P{More PRs?}
O --> P
P -->|Yes| K
P -->|No| Q[Reorganize Commits<br/>Deterministic Bash]
Q --> R[Final Validation<br/>make verify & make test]
R --> S[Create PR]
end
end

subgraph "External Systems"
G <--> GH[(GitHub API<br/>github.com)]
L <--> CLAUDE[Claude API<br/>via Vertex AI]
S <--> FORK[(GitHub Fork<br/>hypershift-community)]
S <--> UPSTREAM[(GitHub Upstream<br/>openshift/hypershift)]
end
```

### Configuration

| Setting | Value | Description |
|---------|-------|-------------|
| Schedule | `0 12 * * 5` | Fridays at 12:00 UTC (7:00 AM ET) |

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Clarify timezone abbreviation for time conversion.

The "ET" (Eastern Time) abbreviation is ambiguous because it doesn't distinguish between EST (UTC-5) and EDT (UTC-4). During daylight saving time, 12:00 UTC is 8:00 AM EDT, not 7:00 AM.

🕐 Suggested fix

Option 1: Use specific timezone

-| Schedule | `0 12 * * 5` | Fridays at 12:00 UTC (7:00 AM ET) |
+| Schedule | `0 12 * * 5` | Fridays at 12:00 UTC (7:00 AM EST / 8:00 AM EDT) |

Option 2: Remove the conversion to avoid confusion

-| Schedule | `0 12 * * 5` | Fridays at 12:00 UTC (7:00 AM ET) |
+| Schedule | `0 12 * * 5` | Fridays at 12:00 UTC |
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
| Schedule | `0 12 * * 5` | Fridays at 12:00 UTC (7:00 AM ET) |
| Schedule | `0 12 * * 5` | Fridays at 12:00 UTC (7:00 AM EST / 8:00 AM EDT) |
Suggested change
| Schedule | `0 12 * * 5` | Fridays at 12:00 UTC (7:00 AM ET) |
| Schedule | `0 12 * * 5` | Fridays at 12:00 UTC |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@docs/content/how-to/ci/ai-assisted-ci-jobs.md` at line 292, The schedule row
showing "0 12 * * 5" currently converts 12:00 UTC to "7:00 AM ET" which is
ambiguous; update the table entry referencing the cron string `0 12 * * 5` to
either (a) use a specific timezone label like "12:00 UTC (8:00 AM EDT / 7:00 AM
EST)" or (b) remove the local-time conversion and simply state "12:00 UTC" to
avoid confusion—apply this change to the table row containing the Schedule/`0 12
* * 5` entry.

| Process timeout | 2 hours | Maximum time for the process step |
| Max Claude turns | 100 | Maximum agentic turns per run |
| Excluded deps | `k8s.io`, `sigs.k8s.io` | Dependencies managed via manual Kubernetes rebases |

### What Gets Excluded

Dependabot PRs bumping the following module prefixes are **automatically skipped**:

- `k8s.io/*` - Core Kubernetes libraries
- `sigs.k8s.io/*` - Kubernetes SIG libraries

These dependencies are updated manually as part of coordinated Kubernetes version rebases to ensure compatibility across the full dependency tree.

---

## User Guide

### Submitting Issues for Processing
Expand All @@ -226,9 +321,10 @@ The issue will be picked up on the next weekly run (Mondays at 8:30 AM UTC).

### Viewing AI-Generated Output

Track PRs created by the Jira Agent:
Track PRs created by the AI agents:

- **PR List**: [github.com/openshift/hypershift/pulls?q=is:pr+author:app/hypershift-jira-solve-ci](https://github.com/openshift/hypershift/pulls?q=is%3Apr+author%3Aapp%2Fhypershift-jira-solve-ci)
- **Jira Agent PRs**: [github.com/openshift/hypershift/pulls?q=is:pr+author:app/hypershift-jira-solve-ci](https://github.com/openshift/hypershift/pulls?q=is%3Apr+author%3Aapp%2Fhypershift-jira-solve-ci)
- **Dependabot Triage PRs**: [github.com/openshift/hypershift/pulls?q=is:pr+head:fix/weekly-dependabot-consolidation](https://github.com/openshift/hypershift/pulls?q=is%3Apr+head%3Afix%2Fweekly-dependabot-consolidation)

PRs are created as **drafts** and require human review before merging.

Expand All @@ -255,7 +351,7 @@ This runs the review agent for that specific PR only.

- **AI may produce incorrect or incomplete solutions** - always review carefully
- **Complex issues may not be fully addressed** - multi-faceted problems may need human intervention
- **Rate limited**: 1 issue per weekly run (jira-agent), 10 PRs per run (review-agent)
- **Rate limited**: 1 issue per weekly run (jira-agent), 10 PRs per run (review-agent), all non-k8s dependabot PRs per run (dependabot-triage)
- **Cannot access private resources** - no access to internal systems beyond Jira/GitHub
- **Cannot execute destructive operations** - no ability to delete resources or force-push
- **Maximum agentic turns**: 100 per issue (jira-agent), 100 per PR (review-agent)
Expand Down
104 changes: 100 additions & 4 deletions docs/content/reference/aggregated-docs.md
Original file line number Diff line number Diff line change
Expand Up @@ -10080,13 +10080,14 @@ This document describes the AI-assisted CI jobs that help automate issue resolut

## Overview

HyperShift uses two AI-assisted CI jobs powered by Claude Code to help with development workflows:
HyperShift uses AI-assisted CI jobs powered by Claude Code to help with development workflows:

| Job | Purpose | Schedule |
|-----|---------|----------|
| `periodic-jira-agent` | Analyzes Jira issues and creates draft PRs with fixes | Weekly on Mondays at 8:30 AM UTC |
| `periodic-review-agent` | Addresses PR review comments on agent-created PRs | Every 3 hours (8:00-23:00 UTC) daily |
| `address-review-comments` | On-demand job to address review comments on a single PR | Triggered via `/test address-review-comments` |
| `periodic-hypershift-dependabot-triage` | Consolidates open dependabot PRs into a single weekly PR | Weekly on Fridays at 12:00 UTC |

### Usage Scope

Expand Down Expand Up @@ -10280,6 +10281,100 @@ flowchart TD

---

## Dependabot Triage Agent

### Overview

The Dependabot Triage Agent (`periodic-hypershift-dependabot-triage`) automatically consolidates open dependabot PRs into a single weekly pull request, reducing noise and simplifying dependency updates.

- **Job name**: `periodic-hypershift-dependabot-triage`
- **Schedule**: Weekly on Fridays at 12:00 UTC (`0 12 * * 5`)
- **Process timeout**: 2 hours
- **Max agentic turns**: 100
- **Jira**: CNTRLPLANE-2588
- **Prow config PR**: openshift/release#73790

### How It Works

1. **Setup**: Verifies Claude Code CLI availability
2. **PR Discovery**: Queries all open dependabot PRs via `gh pr list` on the `openshift/hypershift` repository
3. **Filtering**: Excludes PRs that bump `k8s.io` or `sigs.k8s.io` dependencies (these are managed manually as part of coordinated Kubernetes rebases)
4. **Processing**: Invokes Claude Code to process each PR individually:
- Cherry-picks commits onto a consolidation branch
- Runs `make verify` and `make test` after each PR
- Resets and skips any PR that fails validation
5. **Commit Reorganization** (deterministic bash, not LLM): Flattens all cherry-pick commits via `git reset` and reorganizes into logical groups:
1. Root `go.mod`/`go.sum`
2. Root `vendor/`
3. `api/go.mod`/`api/go.sum`
4. `api/vendor/`
5. `hack/tools/go.mod`/`hack/tools/go.sum`
6. `hack/tools/vendor/`
7. Regenerated CRD assets (`cmd/install/assets/`)
8. Remaining generated files
Empty groups are skipped automatically.
6. **Final Validation**: Runs two-pass `make verify` and `make test` on the consolidated branch
7. **Output**: Creates a single consolidated PR from `hypershift-community:fix/weekly-dependabot-consolidation` to `openshift/hypershift`
8. **Reporting**: Generates an HTML report with token usage, cost breakdown, and detailed output

### Data Flow

```mermaid
flowchart TD
subgraph "Prow CI Environment"
A[Periodic Job Trigger<br/>Weekly Friday 12:00 UTC] --> B[Setup Step]
B --> C[Process Step]
C --> D[Report Step]

subgraph "Process Step"
C --> E[Generate GitHub App Tokens]
E --> F[Clone Fork<br/>hypershift-community/hypershift]
F --> G[Query Open Dependabot PRs]
G --> H{PRs Found?}
H -->|No| I[Exit Successfully]
H -->|Yes| J[Filter Out k8s.io Bumps]
J --> K[For Each PR]
K --> L[Cherry-pick + Validate<br/>make verify & make test]
L --> M{Passed?}
M -->|Yes| N[Keep on Branch]
M -->|No| O[Reset & Skip]
N --> P{More PRs?}
O --> P
P -->|Yes| K
P -->|No| Q[Reorganize Commits<br/>Deterministic Bash]
Q --> R[Final Validation<br/>make verify & make test]
R --> S[Create PR]
end
end

subgraph "External Systems"
G <--> GH[(GitHub API<br/>github.com)]
L <--> CLAUDE[Claude API<br/>via Vertex AI]
S <--> FORK[(GitHub Fork<br/>hypershift-community)]
S <--> UPSTREAM[(GitHub Upstream<br/>openshift/hypershift)]
end
```

### Configuration

| Setting | Value | Description |
|---------|-------|-------------|
| Schedule | `0 12 * * 5` | Fridays at 12:00 UTC (7:00 AM ET) |

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Fix the Eastern Time conversion.

12:00 UTC is not always 7:00 AM ET; during daylight saving time it is 8:00 AM EDT. The current wording will be wrong for part of the year.

🕒 Proposed fix
-| Schedule | `0 12 * * 5` | Fridays at 12:00 UTC (7:00 AM ET) |
+| Schedule | `0 12 * * 5` | Fridays at 12:00 UTC (7:00 AM EST / 8:00 AM EDT) |
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
| Schedule | `0 12 * * 5` | Fridays at 12:00 UTC (7:00 AM ET) |
| Schedule | `0 12 * * 5` | Fridays at 12:00 UTC (7:00 AM EST / 8:00 AM EDT) |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@docs/content/reference/aggregated-docs.md` at line 10362, Update the
human-readable timezone text for the schedule entry with cron string `0 12 * *
5` so it correctly reflects US Eastern time during standard and daylight time;
replace "Fridays at 12:00 UTC (7:00 AM ET)" with something like "Fridays at
12:00 UTC (7:00 AM EST / 8:00 AM EDT)" or "Fridays at 12:00 UTC — 7:00 AM EST
(8:00 AM EDT during DST)" so both offsets are shown and the wording is accurate
year-round.

| Process timeout | 2 hours | Maximum time for the process step |
| Max Claude turns | 100 | Maximum agentic turns per run |
| Excluded deps | `k8s.io`, `sigs.k8s.io` | Dependencies managed via manual Kubernetes rebases |

### What Gets Excluded

Dependabot PRs bumping the following module prefixes are **automatically skipped**:

- `k8s.io/*` - Core Kubernetes libraries
- `sigs.k8s.io/*` - Kubernetes SIG libraries

These dependencies are updated manually as part of coordinated Kubernetes version rebases to ensure compatibility across the full dependency tree.

---

## User Guide

### Submitting Issues for Processing
Expand All @@ -10296,9 +10391,10 @@ The issue will be picked up on the next weekly run (Mondays at 8:30 AM UTC).

### Viewing AI-Generated Output

Track PRs created by the Jira Agent:
Track PRs created by the AI agents:

- **PR List**: github.com/openshift/hypershift/pulls?q=is:pr+author:app/hypershift-jira-solve-ci
- **Jira Agent PRs**: github.com/openshift/hypershift/pulls?q=is:pr+author:app/hypershift-jira-solve-ci
- **Dependabot Triage PRs**: github.com/openshift/hypershift/pulls?q=is:pr+head:fix/weekly-dependabot-consolidation
Comment on lines +10396 to +10397

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Use explicit Markdown links for the GitHub searches.

These are raw hostnames with query strings. In MkDocs, that is not guaranteed to render as clickable links, which makes the “Viewing AI-Generated Output” section brittle.

🔗 Proposed fix
-- **Jira Agent PRs**: github.com/openshift/hypershift/pulls?q=is:pr+author:app/hypershift-jira-solve-ci
-- **Dependabot Triage PRs**: github.com/openshift/hypershift/pulls?q=is:pr+head:fix/weekly-dependabot-consolidation
+- **Jira Agent PRs**: [openshift/hypershift PRs authored by hypershift-jira-solve-ci](https://github.com/openshift/hypershift/pulls?q=is%3Apr+author%3Aapp%2Fhypershift-jira-solve-ci)
+- **Dependabot Triage PRs**: [openshift/hypershift PRs from `fix/weekly-dependabot-consolidation`](https://github.com/openshift/hypershift/pulls?q=is%3Apr+head%3Afix%2Fweekly-dependabot-consolidation)
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
- **Jira Agent PRs**: github.com/openshift/hypershift/pulls?q=is:pr+author:app/hypershift-jira-solve-ci
- **Dependabot Triage PRs**: github.com/openshift/hypershift/pulls?q=is:pr+head:fix/weekly-dependabot-consolidation
- **Jira Agent PRs**: [openshift/hypershift PRs authored by hypershift-jira-solve-ci](https://github.com/openshift/hypershift/pulls?q=is%3Apr+author%3Aapp%2Fhypershift-jira-solve-ci)
- **Dependabot Triage PRs**: [openshift/hypershift PRs from `fix/weekly-dependabot-consolidation`](https://github.com/openshift/hypershift/pulls?q=is%3Apr+head%3Afix%2Fweekly-dependabot-consolidation)
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@docs/content/reference/aggregated-docs.md` around lines 10396 - 10397,
Replace the raw hostname+query strings with explicit Markdown links so MkDocs
renders them as clickable links: update the lines for "Jira Agent PRs" and
"Dependabot Triage PRs" to use the [label](https://...) Markdown link format
(keeping the visible labels "Jira Agent PRs" and "Dependabot Triage PRs" intact
and the existing GitHub search URLs as the targets) so the two entries become
proper Markdown links.


PRs are created as **drafts** and require human review before merging.

Expand All @@ -10325,7 +10421,7 @@ This runs the review agent for that specific PR only.

- **AI may produce incorrect or incomplete solutions** - always review carefully
- **Complex issues may not be fully addressed** - multi-faceted problems may need human intervention
- **Rate limited**: 1 issue per weekly run (jira-agent), 10 PRs per run (review-agent)
- **Rate limited**: 1 issue per weekly run (jira-agent), 10 PRs per run (review-agent), all non-k8s dependabot PRs per run (dependabot-triage)
- **Cannot access private resources** - no access to internal systems beyond Jira/GitHub
- **Cannot execute destructive operations** - no ability to delete resources or force-push
- **Maximum agentic turns**: 100 per issue (jira-agent), 100 per PR (review-agent)
Expand Down