From 241b323cd232fd8f5238290bcf9b550d74792468 Mon Sep 17 00:00:00 2001 From: openhands Date: Tue, 14 Apr 2026 14:44:25 +0000 Subject: [PATCH 1/8] feat: redesign automation examples as card-based marketplace linked to use cases MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Redesign automation examples page with card-based UI organized into 'Use Case Automations' and 'General Automations' sections - Each use-case automation card links to the full guide, relevant plugin, and includes a copyable prompt with Prompt/Plugin tabs - General automations displayed as a 3-column card grid for discoverability - Tips section collapsed into AccordionGroup to reduce visual noise - Add 'Automate This' sections to 4 use case pages (vulnerability remediation, code review, incident triage, dependency upgrades) with ready-to-use automation prompts and link to the examples page - Update use-cases overview with new 'Automate Any Use Case' section showing cards for Automation Templates, Plugins, and SDK - Cross-link use cases ↔ automations ↔ plugins bidirectionally Co-authored-by: openhands --- openhands/usage/automations/examples.mdx | 226 +++++++++++++----- openhands/usage/use-cases/code-review.mdx | 17 ++ .../usage/use-cases/dependency-upgrades.mdx | 18 ++ openhands/usage/use-cases/incident-triage.mdx | 16 ++ openhands/usage/use-cases/overview.mdx | 18 ++ .../use-cases/vulnerability-remediation.mdx | 19 ++ 6 files changed, 248 insertions(+), 66 deletions(-) diff --git a/openhands/usage/automations/examples.mdx b/openhands/usage/automations/examples.mdx index 5a5fec4e9..f6edccd11 100644 --- a/openhands/usage/automations/examples.mdx +++ b/openhands/usage/automations/examples.mdx @@ -1,19 +1,153 @@ --- title: Automation Examples -description: Practical examples for common automation use cases. +description: Ready-to-use automation templates organized by use case. Copy a prompt, paste it into OpenHands, and you're running. --- **Beta Feature**: Automations is currently in beta and available for **OpenHands Cloud** and **OpenHands Enterprise** users only. -Copy and adapt these examples to create your own automations. Just paste the prompt into a conversation with OpenHands. +Browse automation templates below. Each card includes a ready-to-use prompt—just copy it into an OpenHands conversation and the agent will set everything up for you. These examples reference services like Slack and GitHub. Git providers you logged in with are automatically available, but other services like Slack require [MCP configuration](/openhands/usage/settings/mcp-settings). -## Reporting +## Use Case Automations + +These automations correspond to documented [use cases](/openhands/usage/use-cases/overview). Each card links to the full use case guide, the relevant plugin or SDK example, and a prompt you can copy directly. + + + + Scan dependencies for known CVEs and post a report. Pairs with the [vulnerability-remediation plugin](https://github.com/OpenHands/extensions/tree/main/plugins/vulnerability-remediation). + + + Review PRs automatically on every push. Pairs with the [pr-review plugin](https://github.com/OpenHands/extensions/tree/main/plugins/pr-review). + + + Monitor APIs, analyze errors, and alert your team. Pairs with the [Datadog debugging workflow](https://github.com/OpenHands/software-agent-sdk/tree/main/examples/03_github_workflows/04_datadog_debugging). + + + Check for outdated packages weekly and report available updates. + + + +### Vulnerability Scan + + + + ``` + Create an automation called "Security Scan" that runs daily at 3 AM. + + It should run a security audit: + 1. Check for known vulnerabilities in dependencies + 2. Scan for hardcoded secrets or API keys + 3. Look for common security misconfigurations + + Create a detailed report and alert #security if any high or critical issues are found. + ``` + + + Use the [vulnerability-remediation plugin](https://github.com/OpenHands/extensions/tree/main/plugins/vulnerability-remediation) for a more thorough scan with automated fix PRs. See the [full use case guide](/openhands/usage/use-cases/vulnerability-remediation). + + + +### Automated Code Review + + + + ``` + Create an automation called "Daily Code Review" that runs every weekday at 9 AM. + + It should: + 1. Find all open PRs that have no reviews yet + 2. For each PR, review the diff for bugs, style issues, and security concerns + 3. Post a summary of findings as a comment on each PR + ``` + + + Use the [pr-review plugin](https://github.com/OpenHands/extensions/tree/main/plugins/pr-review) for inline review comments on every PR. See the [full use case guide](/openhands/usage/use-cases/code-review). + + + +### Incident Monitoring + + + + ``` + Create an automation called "API Health Monitor" that runs every 30 minutes. + + It should check https://api.example.com/health and: + - If the response is not 200 OK, send an alert to #alerts with the status code and response body + - If healthy, just log success without alerting anyone + ``` + + + Use the [Datadog debugging workflow](https://github.com/OpenHands/software-agent-sdk/tree/main/examples/03_github_workflows/04_datadog_debugging) for deeper error analysis with Datadog integration. See the [full use case guide](/openhands/usage/use-cases/incident-triage). + + + +### Dependency Upgrades + + + + ``` + Create an automation called "Dependency Checker" that runs every Monday at 8 AM. + + It should: + 1. Scan all package.json and requirements.txt files + 2. Check for outdated dependencies + 3. Create a report listing packages with available updates (grouped by major/minor/patch) + 4. Post the report to #engineering + ``` + + + See the [full use case guide](/openhands/usage/use-cases/dependency-upgrades) for strategies on handling breaking changes, planning major upgrades, and validating after updates. + + + +--- + +## General Automations + +Ready-to-use templates for common operational tasks. + + + + Summarize PRs opened, merged, and reviewed daily. + + + Generate weekly GitHub activity and issue reports. + + + Check SSL expiry dates and alert before they lapse. + + + Remove stale temporary files and report what was cleaned. + + + Verify database backups exist and are recent. + + + Pull analytics data periodically and flag big changes. + + ### Daily GitHub Summary @@ -40,18 +174,6 @@ It should generate a weekly report covering: Save the report to weekly-reports/ with the current date in the filename. ``` -## Monitoring - -### API Health Check - -``` -Create an automation called "API Health Monitor" that runs every 30 minutes. - -It should check https://api.example.com/health and: -- If the response is not 200 OK, send an alert to #alerts with the status code and response body -- If healthy, just log success without alerting anyone -``` - ### SSL Certificate Monitor ``` @@ -59,14 +181,12 @@ Create an automation called "SSL Monitor" that runs daily at 8 AM. It should check SSL certificate expiry for these domains: - api.example.com -- app.example.com +- app.example.com - www.example.com If any certificate expires within 30 days, alert #devops with the domain and days remaining. ``` -## Maintenance - ### Weekly Cleanup ``` @@ -88,8 +208,6 @@ List the most recent backup for each database with its timestamp and size. If any backup is missing or stale, send an urgent alert to #alerts. ``` -## Data Sync - ### Analytics Data Sync ``` @@ -102,57 +220,33 @@ It should: 4. If any metric changed by more than 20%, flag it in a summary message ``` -## Code Quality - -### Dependency Checker - -``` -Create an automation called "Dependency Checker" that runs every Monday at 8 AM. - -It should: -1. Scan all package.json and requirements.txt files -2. Check for outdated dependencies -3. Create a report listing packages with available updates (grouped by major/minor/patch) -4. Post the report to #engineering -``` - -### Security Scan - -``` -Create an automation called "Security Scan" that runs daily at 3 AM. - -It should run a security audit: -1. Check for known vulnerabilities in dependencies -2. Scan for hardcoded secrets or API keys -3. Look for common security misconfigurations - -Create a detailed report and alert #security if any high or critical issues are found. -``` +--- ## Tips for Writing Good Prompts -### Be Specific About Actions - -Tell the automation exactly what to do: -- "Check X and if Y, then Z" -- "Generate a report and save it to..." -- "Fetch data, compare with expected values, and report differences" - -### Include Error Handling - -Specify what should happen when things go wrong: -- "If the response is not 200..." -- "If any backup is missing..." -- "If the check fails, alert the team" - -### Define Where Results Go - -Be explicit about outputs: -- "Post to the #channel Slack channel" -- "Save to reports/ with the current date" -- "Create a GitHub issue with the findings" + + + Tell the automation exactly what to do: + - "Check X and if Y, then Z" + - "Generate a report and save it to..." + - "Fetch data, compare with expected values, and report differences" + + + Specify what should happen when things go wrong: + - "If the response is not 200..." + - "If any backup is missing..." + - "If the check fails, alert the team" + + + Be explicit about outputs: + - "Post to the #channel Slack channel" + - "Save to reports/ with the current date" + - "Create a GitHub issue with the findings" + + ## Next Steps - [Creating Automations](/openhands/usage/automations/creating-automations) — More details on writing prompts - [Managing Automations](/openhands/usage/automations/managing-automations) — Update, disable, or delete automations +- [Use Cases Overview](/openhands/usage/use-cases/overview) — Explore the full use case guides behind these automations diff --git a/openhands/usage/use-cases/code-review.mdx b/openhands/usage/use-cases/code-review.mdx index 52b1b78af..f53c5a281 100644 --- a/openhands/usage/use-cases/code-review.mdx +++ b/openhands/usage/use-cases/code-review.mdx @@ -266,6 +266,23 @@ See real automated reviews in action on the OpenHands Software Agent SDK reposit +## Automate This + +Schedule daily code reviews with an OpenHands automation. Copy this prompt into a conversation: + +``` +Create an automation called "Daily Code Review" that runs every weekday at 9 AM. + +It should: +1. Find all open PRs that have no reviews yet +2. For each PR, review the diff for bugs, style issues, and security concerns +3. Post a summary of findings as a comment on each PR +``` + + + Browse all automation examples, including vulnerability scanning, code review, monitoring, and more. + + ## Related Resources - [PR Review Workflow Reference](https://github.com/OpenHands/software-agent-sdk/tree/main/examples/03_github_workflows/02_pr_review) - Full workflow example and agent script diff --git a/openhands/usage/use-cases/dependency-upgrades.mdx b/openhands/usage/use-cases/dependency-upgrades.mdx index 7dad9000b..afcf7a2cb 100644 --- a/openhands/usage/use-cases/dependency-upgrades.mdx +++ b/openhands/usage/use-cases/dependency-upgrades.mdx @@ -277,6 +277,24 @@ Create an upgrade plan that handles all these together, addressing breaking changes in the correct order. ``` +## Automate This + +Schedule weekly dependency checks with an OpenHands automation. Copy this prompt into a conversation: + +``` +Create an automation called "Dependency Checker" that runs every Monday at 8 AM. + +It should: +1. Scan all package.json and requirements.txt files +2. Check for outdated dependencies +3. Create a report listing packages with available updates (grouped by major/minor/patch) +4. Post the report to #engineering +``` + + + Browse all automation examples, including vulnerability scanning, code review, monitoring, and more. + + ## Related Resources - [Vulnerability Remediation](/openhands/usage/use-cases/vulnerability-remediation) - Fix security vulnerabilities diff --git a/openhands/usage/use-cases/incident-triage.mdx b/openhands/usage/use-cases/incident-triage.mdx index 6f816f1ff..b962ed921 100644 --- a/openhands/usage/use-cases/incident-triage.mdx +++ b/openhands/usage/use-cases/incident-triage.mdx @@ -257,6 +257,22 @@ Avoid these common incident response mistakes: For production incidents, always follow your organization's incident response procedures. OpenHands is a tool to assist your investigation, not a replacement for proper incident management. +## Automate This + +Set up continuous health monitoring with an OpenHands automation. Copy this prompt into a conversation: + +``` +Create an automation called "API Health Monitor" that runs every 30 minutes. + +It should check https://api.example.com/health and: +- If the response is not 200 OK, send an alert to #alerts with the status code and response body +- If healthy, just log success without alerting anyone +``` + + + Browse all automation examples, including vulnerability scanning, code review, monitoring, and more. + + ## Related Resources - [OpenHands SDK Repository](https://github.com/OpenHands/software-agent-sdk) - Build custom AI agents diff --git a/openhands/usage/use-cases/overview.mdx b/openhands/usage/use-cases/overview.mdx index cb1d09cca..76bc55d0f 100644 --- a/openhands/usage/use-cases/overview.mdx +++ b/openhands/usage/use-cases/overview.mdx @@ -5,6 +5,8 @@ description: Explore how OpenHands can help with common software development cha OpenHands supports a wide variety of software development tasks. Here are some of the key use cases where OpenHands can help accelerate your work. +Each use case can be implemented in different ways—as a one-off conversation, a scheduled [automation](/openhands/usage/automations/examples), a [plugin](https://github.com/OpenHands/extensions), or through the [SDK](/sdk/index). Pick the approach that fits your workflow. + + +## Automate Any Use Case + +Many use cases work best as scheduled automations. Browse ready-to-use automation templates on the [Automation Examples](/openhands/usage/automations/examples) page—just copy a prompt and paste it into OpenHands. + + + + Ready-to-use prompts for vulnerability scans, code reviews, monitoring, and more. + + + Explore plugins in the OpenHands extensions repository for extended capabilities. + + + Build custom workflows and integrations using the Software Agent SDK. + + diff --git a/openhands/usage/use-cases/vulnerability-remediation.mdx b/openhands/usage/use-cases/vulnerability-remediation.mdx index f414db4d1..580de2443 100644 --- a/openhands/usage/use-cases/vulnerability-remediation.mdx +++ b/openhands/usage/use-cases/vulnerability-remediation.mdx @@ -276,6 +276,25 @@ To build your own vulnerability remediation agent: As agent capabilities continue to evolve, an increasing number of repetitive and time-consuming security tasks can be automated, enabling developers to focus on higher-level design, innovation, and problem-solving rather than routine maintenance. +## Automate This + +Run vulnerability scans on a schedule with an OpenHands automation. Copy this prompt into a conversation: + +``` +Create an automation called "Security Scan" that runs daily at 3 AM. + +It should run a security audit: +1. Check for known vulnerabilities in dependencies +2. Scan for hardcoded secrets or API keys +3. Look for common security misconfigurations + +Create a detailed report and alert #security if any high or critical issues are found. +``` + + + Browse all automation examples, including vulnerability scanning, code review, monitoring, and more. + + ## Related Resources - [Vulnerability Fixer Example](https://github.com/OpenHands/vulnerability-fixer) - Full implementation example From ab8861ef95cecbe912c3cafa03a6b3424fdde526 Mon Sep 17 00:00:00 2001 From: openhands Date: Tue, 14 Apr 2026 14:50:57 +0000 Subject: [PATCH 2/8] feat: add CI workflow to auto-sync use-case automation cards from YAML data MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add _data/use-case-automations.yaml as single source of truth for use-case → automation mappings (title, icon, prompt, plugin link, etc.) - Add .github/scripts/sync_use_case_automations.py to generate/validate the auto-generated MDX sections between marker comments - Add .github/workflows/sync-use-case-automations.yml CI check that runs on PRs touching the data file, examples page, or use-case pages - Add {/* BEGIN/END */} marker comments to examples.mdx and 4 use-case pages so the script knows which sections to regenerate Workflow: 1. Edit _data/use-case-automations.yaml (add/modify use cases) 2. Run: python .github/scripts/sync_use_case_automations.py 3. Commit the YAML + regenerated MDX files 4. CI validates everything stays in sync Co-authored-by: openhands --- .github/scripts/sync_use_case_automations.py | 233 ++++++++++++++++++ .../workflows/sync-use-case-automations.yml | 40 +++ _data/use-case-automations.yaml | 101 ++++++++ openhands/usage/automations/examples.mdx | 4 + openhands/usage/use-cases/code-review.mdx | 4 + .../usage/use-cases/dependency-upgrades.mdx | 4 + openhands/usage/use-cases/incident-triage.mdx | 4 + .../use-cases/vulnerability-remediation.mdx | 4 + 8 files changed, 394 insertions(+) create mode 100644 .github/scripts/sync_use_case_automations.py create mode 100644 .github/workflows/sync-use-case-automations.yml create mode 100644 _data/use-case-automations.yaml diff --git a/.github/scripts/sync_use_case_automations.py b/.github/scripts/sync_use_case_automations.py new file mode 100644 index 000000000..f3ea5c976 --- /dev/null +++ b/.github/scripts/sync_use_case_automations.py @@ -0,0 +1,233 @@ +#!/usr/bin/env python3 +""" +Sync use-case automation cards across documentation pages. + +Reads ``_data/use-case-automations.yaml`` (the single source of truth) and +regenerates the marked sections in: + +* ``openhands/usage/automations/examples.mdx`` — card grid + Tabs per use case +* ``openhands/usage/use-cases/.mdx`` — "Automate This" section + +The script replaces content between marker comments: + {/* BEGIN: ... */} … {/* END: */} + +Exit codes: + 0 — all files are in sync (or were updated with --write) + 1 — files are out of sync (CI check mode) +""" + +from __future__ import annotations + +import argparse +import re +import sys +import textwrap +from pathlib import Path + +import yaml + +REPO_ROOT = Path(__file__).resolve().parents[2] +DATA_FILE = REPO_ROOT / "_data" / "use-case-automations.yaml" +EXAMPLES_PAGE = REPO_ROOT / "openhands" / "usage" / "automations" / "examples.mdx" +USE_CASES_DIR = REPO_ROOT / "openhands" / "usage" / "use-cases" + +BEGIN_RE = re.compile( + r"\{/\*\s*BEGIN:([\w-]+)\s*(?:—[^*]*)?\*/\}" +) +END_RE = re.compile( + r"\{/\*\s*END:([\w-]+)\s*\*/\}" +) + + +def load_data() -> list[dict]: + with open(DATA_FILE) as f: + return yaml.safe_load(f)["use_cases"] + + +# ── Generators ──────────────────────────────────────────────────────── + +def _indent(text: str, n: int = 4) -> str: + return textwrap.indent(text, " " * n) + + +def _prompt_block(prompt: str, indent: int = 4) -> str: + """Wrap a prompt string in a fenced code block, indented.""" + lines = prompt.rstrip("\n").split("\n") + block = "```\n" + "\n".join(lines) + "\n```" + return _indent(block, indent) + + +def generate_examples_section(use_cases: list[dict]) -> str: + """Generate the ``use-case-automations`` block for *examples.mdx*.""" + parts: list[str] = [] + + parts.append( + "## Use Case Automations\n" + "\n" + "These automations correspond to documented " + "[use cases](/openhands/usage/use-cases/overview). " + "Each card links to the full use case guide, the relevant plugin " + "or SDK example, and a prompt you can copy directly.\n" + "\n" + "" + ) + + # Cards + for uc in use_cases: + parts.append( + f' \n' + f' {uc["card_description"]}\n' + f' ' + ) + + parts.append("") + + # Tabs per use case + for uc in use_cases: + parts.append(f'\n### {uc["title"]}') + parts.append("") + parts.append("") + parts.append(' ') + parts.append(_prompt_block(uc["automation_prompt"])) + parts.append(" ") + parts.append(f' ') + parts.append(f' {uc["alt_tab_body"]}') + parts.append(" ") + parts.append("") + + return "\n".join(parts) + + +def generate_automate_this(uc: dict) -> str: + """Generate the ``automate-this`` block for a single use-case page.""" + prompt = uc["automation_prompt"].rstrip("\n") + return ( + f"## Automate This\n" + f"\n" + f'{uc["use_case_intro"]}\n' + f"\n" + f"```\n" + f"{prompt}\n" + f"```\n" + f"\n" + f'\n' + f" Browse all automation examples, including vulnerability scanning, " + f"code review, monitoring, and more.\n" + f"" + ) + + +# ── Marker replacement ─────────────────────────────────────────────── + +def replace_marker_section( + content: str, marker: str, new_body: str +) -> str: + """Replace everything between BEGIN: and END:.""" + begin_pattern = re.compile( + rf"\{{/\*\s*BEGIN:{re.escape(marker)}\s*(?:—[^*]*)?\*/\}}" + ) + end_pattern = re.compile( + rf"\{{/\*\s*END:{re.escape(marker)}\s*\*/\}}" + ) + + begin_match = begin_pattern.search(content) + end_match = end_pattern.search(content) + + if not begin_match or not end_match: + return content # markers not found — skip + + begin_tag = begin_match.group(0) + end_tag = end_match.group(0) + + before = content[: begin_match.start()] + after = content[end_match.end() :] + + return f"{before}{begin_tag}\n\n{new_body}\n\n{end_tag}{after}" + + +# ── Main ────────────────────────────────────────────────────────────── + +def main() -> int: + parser = argparse.ArgumentParser( + description="Sync use-case automation cards from YAML data to MDX pages." + ) + parser.add_argument( + "--check", + action="store_true", + help="Check mode: exit 1 if files are out of sync (for CI).", + ) + args = parser.parse_args() + + use_cases = load_data() + diffs: list[str] = [] + + # 1. Update examples.mdx + original = EXAMPLES_PAGE.read_text() + generated = generate_examples_section(use_cases) + updated = replace_marker_section(original, "use-case-automations", generated) + + if updated != original: + diffs.append(str(EXAMPLES_PAGE.relative_to(REPO_ROOT))) + if not args.check: + EXAMPLES_PAGE.write_text(updated) + print(f" ✏️ Updated {EXAMPLES_PAGE.relative_to(REPO_ROOT)}") + + # 2. Update individual use-case pages + for uc in use_cases: + page = USE_CASES_DIR / f'{uc["slug"]}.mdx' + if not page.exists(): + print(f" ⚠️ Use-case page not found: {page.relative_to(REPO_ROOT)}") + diffs.append(str(page.relative_to(REPO_ROOT)) + " (missing)") + continue + + original = page.read_text() + generated = generate_automate_this(uc) + updated = replace_marker_section(original, "automate-this", generated) + + if updated != original: + diffs.append(str(page.relative_to(REPO_ROOT))) + if not args.check: + page.write_text(updated) + print(f" ✏️ Updated {page.relative_to(REPO_ROOT)}") + + # 3. Check for use-case pages without automation entries + existing_slugs = {uc["slug"] for uc in use_cases} + for page in sorted(USE_CASES_DIR.glob("*.mdx")): + if page.name == "overview.mdx": + continue + slug = page.stem + if slug not in existing_slugs: + content = page.read_text() + if BEGIN_RE.search(content): + # Has markers but no YAML entry — stale + print( + f" ⚠️ {page.relative_to(REPO_ROOT)} has automation markers " + f"but no entry in {DATA_FILE.relative_to(REPO_ROOT)}" + ) + + if diffs: + if args.check: + print("\n❌ Files are out of sync with " + f"{DATA_FILE.relative_to(REPO_ROOT)}:") + for d in diffs: + print(f" - {d}") + print( + "\nRun: python .github/scripts/sync_use_case_automations.py\n" + "Then commit the updated files." + ) + return 1 + else: + print(f"\n✅ Updated {len(diffs)} file(s).") + else: + print("✅ All files are in sync.") + + return 0 + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/.github/workflows/sync-use-case-automations.yml b/.github/workflows/sync-use-case-automations.yml new file mode 100644 index 000000000..69ccb7163 --- /dev/null +++ b/.github/workflows/sync-use-case-automations.yml @@ -0,0 +1,40 @@ +name: Sync Use-Case Automations + +on: + pull_request: + branches: + - '**' + paths: + - '_data/use-case-automations.yaml' + - 'openhands/usage/automations/examples.mdx' + - 'openhands/usage/use-cases/**' + - '.github/scripts/sync_use_case_automations.py' + - '.github/workflows/sync-use-case-automations.yml' + push: + branches: + - main + paths: + - '_data/use-case-automations.yaml' + - '.github/scripts/sync_use_case_automations.py' + +permissions: + contents: read + +jobs: + check-sync: + name: Check use-case ↔ automation sync + runs-on: ubuntu-latest + steps: + - name: Checkout repository + uses: actions/checkout@v4 + + - name: Setup Python + uses: actions/setup-python@v5 + with: + python-version: '3.12' + + - name: Install dependencies + run: pip install pyyaml + + - name: Validate sync + run: python .github/scripts/sync_use_case_automations.py --check diff --git a/_data/use-case-automations.yaml b/_data/use-case-automations.yaml new file mode 100644 index 000000000..a1a101333 --- /dev/null +++ b/_data/use-case-automations.yaml @@ -0,0 +1,101 @@ +# Single source of truth for use-case → automation mappings. +# +# A CI workflow (`sync-use-case-automations.yml`) reads this file and +# regenerates the auto-generated sections in: +# - openhands/usage/automations/examples.mdx (card grid + Tabs per use case) +# - openhands/usage/use-cases/.mdx ("Automate This" section) +# +# To add a new use case automation: +# 1. Add an entry below. +# 2. Run: python .github/scripts/sync_use_case_automations.py +# 3. Commit the updated MDX files together with this YAML change. + +use_cases: + - slug: vulnerability-remediation + title: Vulnerability Scan + icon: shield-halved + card_description: >- + Scan dependencies for known CVEs and post a report. Pairs with the + [vulnerability-remediation plugin](https://github.com/OpenHands/extensions/tree/main/plugins/vulnerability-remediation). + use_case_intro: >- + Run vulnerability scans on a schedule with an OpenHands automation. + Copy this prompt into a conversation: + automation_prompt: | + Create an automation called "Security Scan" that runs daily at 3 AM. + + It should run a security audit: + 1. Check for known vulnerabilities in dependencies + 2. Scan for hardcoded secrets or API keys + 3. Look for common security misconfigurations + + Create a detailed report and alert #security if any high or critical issues are found. + alt_tab_title: Plugin + alt_tab_body: >- + Use the [vulnerability-remediation plugin](https://github.com/OpenHands/extensions/tree/main/plugins/vulnerability-remediation) + for a more thorough scan with automated fix PRs. See the + [full use case guide](/openhands/usage/use-cases/vulnerability-remediation). + + - slug: code-review + title: Automated Code Review + icon: code-pull-request + card_description: >- + Review PRs automatically on every push. Pairs with the + [pr-review plugin](https://github.com/OpenHands/extensions/tree/main/plugins/pr-review). + use_case_intro: >- + Schedule daily code reviews with an OpenHands automation. + Copy this prompt into a conversation: + automation_prompt: | + Create an automation called "Daily Code Review" that runs every weekday at 9 AM. + + It should: + 1. Find all open PRs that have no reviews yet + 2. For each PR, review the diff for bugs, style issues, and security concerns + 3. Post a summary of findings as a comment on each PR + alt_tab_title: Plugin + alt_tab_body: >- + Use the [pr-review plugin](https://github.com/OpenHands/extensions/tree/main/plugins/pr-review) + for inline review comments on every PR. See the + [full use case guide](/openhands/usage/use-cases/code-review). + + - slug: incident-triage + title: Incident Monitoring + icon: triangle-exclamation + card_description: >- + Monitor APIs, analyze errors, and alert your team. Pairs with the + [Datadog debugging workflow](https://github.com/OpenHands/software-agent-sdk/tree/main/examples/03_github_workflows/04_datadog_debugging). + use_case_intro: >- + Set up continuous health monitoring with an OpenHands automation. + Copy this prompt into a conversation: + automation_prompt: | + Create an automation called "API Health Monitor" that runs every 30 minutes. + + It should check https://api.example.com/health and: + - If the response is not 200 OK, send an alert to #alerts with the status code and response body + - If healthy, just log success without alerting anyone + alt_tab_title: Plugin + alt_tab_body: >- + Use the [Datadog debugging workflow](https://github.com/OpenHands/software-agent-sdk/tree/main/examples/03_github_workflows/04_datadog_debugging) + for deeper error analysis with Datadog integration. See the + [full use case guide](/openhands/usage/use-cases/incident-triage). + + - slug: dependency-upgrades + title: Dependency Upgrades + icon: arrow-up-right-dots + card_description: >- + Check for outdated packages weekly and report available updates. + use_case_intro: >- + Schedule weekly dependency checks with an OpenHands automation. + Copy this prompt into a conversation: + automation_prompt: | + Create an automation called "Dependency Checker" that runs every Monday at 8 AM. + + It should: + 1. Scan all package.json and requirements.txt files + 2. Check for outdated dependencies + 3. Create a report listing packages with available updates (grouped by major/minor/patch) + 4. Post the report to #engineering + alt_tab_title: Learn More + alt_tab_body: >- + See the [full use case guide](/openhands/usage/use-cases/dependency-upgrades) + for strategies on handling breaking changes, planning major upgrades, + and validating after updates. diff --git a/openhands/usage/automations/examples.mdx b/openhands/usage/automations/examples.mdx index f6edccd11..295fb5039 100644 --- a/openhands/usage/automations/examples.mdx +++ b/openhands/usage/automations/examples.mdx @@ -13,6 +13,8 @@ Browse automation templates below. Each card includes a ready-to-use prompt—ju These examples reference services like Slack and GitHub. Git providers you logged in with are automatically available, but other services like Slack require [MCP configuration](/openhands/usage/settings/mcp-settings). +{/* BEGIN:use-case-automations — auto-generated from _data/use-case-automations.yaml */} + ## Use Case Automations These automations correspond to documented [use cases](/openhands/usage/use-cases/overview). Each card links to the full use case guide, the relevant plugin or SDK example, and a prompt you can copy directly. @@ -122,6 +124,8 @@ These automations correspond to documented [use cases](/openhands/usage/use-case +{/* END:use-case-automations */} + --- ## General Automations diff --git a/openhands/usage/use-cases/code-review.mdx b/openhands/usage/use-cases/code-review.mdx index f53c5a281..7617ac2d2 100644 --- a/openhands/usage/use-cases/code-review.mdx +++ b/openhands/usage/use-cases/code-review.mdx @@ -266,6 +266,8 @@ See real automated reviews in action on the OpenHands Software Agent SDK reposit +{/* BEGIN:automate-this — auto-generated from _data/use-case-automations.yaml */} + ## Automate This Schedule daily code reviews with an OpenHands automation. Copy this prompt into a conversation: @@ -283,6 +285,8 @@ It should: Browse all automation examples, including vulnerability scanning, code review, monitoring, and more. +{/* END:automate-this */} + ## Related Resources - [PR Review Workflow Reference](https://github.com/OpenHands/software-agent-sdk/tree/main/examples/03_github_workflows/02_pr_review) - Full workflow example and agent script diff --git a/openhands/usage/use-cases/dependency-upgrades.mdx b/openhands/usage/use-cases/dependency-upgrades.mdx index afcf7a2cb..16d7dd234 100644 --- a/openhands/usage/use-cases/dependency-upgrades.mdx +++ b/openhands/usage/use-cases/dependency-upgrades.mdx @@ -277,6 +277,8 @@ Create an upgrade plan that handles all these together, addressing breaking changes in the correct order. ``` +{/* BEGIN:automate-this — auto-generated from _data/use-case-automations.yaml */} + ## Automate This Schedule weekly dependency checks with an OpenHands automation. Copy this prompt into a conversation: @@ -295,6 +297,8 @@ It should: Browse all automation examples, including vulnerability scanning, code review, monitoring, and more. +{/* END:automate-this */} + ## Related Resources - [Vulnerability Remediation](/openhands/usage/use-cases/vulnerability-remediation) - Fix security vulnerabilities diff --git a/openhands/usage/use-cases/incident-triage.mdx b/openhands/usage/use-cases/incident-triage.mdx index b962ed921..c362c9c1a 100644 --- a/openhands/usage/use-cases/incident-triage.mdx +++ b/openhands/usage/use-cases/incident-triage.mdx @@ -257,6 +257,8 @@ Avoid these common incident response mistakes: For production incidents, always follow your organization's incident response procedures. OpenHands is a tool to assist your investigation, not a replacement for proper incident management. +{/* BEGIN:automate-this — auto-generated from _data/use-case-automations.yaml */} + ## Automate This Set up continuous health monitoring with an OpenHands automation. Copy this prompt into a conversation: @@ -273,6 +275,8 @@ It should check https://api.example.com/health and: Browse all automation examples, including vulnerability scanning, code review, monitoring, and more. +{/* END:automate-this */} + ## Related Resources - [OpenHands SDK Repository](https://github.com/OpenHands/software-agent-sdk) - Build custom AI agents diff --git a/openhands/usage/use-cases/vulnerability-remediation.mdx b/openhands/usage/use-cases/vulnerability-remediation.mdx index 580de2443..31b55c40e 100644 --- a/openhands/usage/use-cases/vulnerability-remediation.mdx +++ b/openhands/usage/use-cases/vulnerability-remediation.mdx @@ -276,6 +276,8 @@ To build your own vulnerability remediation agent: As agent capabilities continue to evolve, an increasing number of repetitive and time-consuming security tasks can be automated, enabling developers to focus on higher-level design, innovation, and problem-solving rather than routine maintenance. +{/* BEGIN:automate-this — auto-generated from _data/use-case-automations.yaml */} + ## Automate This Run vulnerability scans on a schedule with an OpenHands automation. Copy this prompt into a conversation: @@ -295,6 +297,8 @@ Create a detailed report and alert #security if any high or critical issues are Browse all automation examples, including vulnerability scanning, code review, monitoring, and more. +{/* END:automate-this */} + ## Related Resources - [Vulnerability Fixer Example](https://github.com/OpenHands/vulnerability-fixer) - Full implementation example From bd7d014f0ad383da647f668ab3ffd281ca9d615e Mon Sep 17 00:00:00 2001 From: openhands Date: Tue, 14 Apr 2026 14:58:28 +0000 Subject: [PATCH 3/8] refactor: use frontmatter as source of truth instead of separate YAML file MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The automation content for each use case is now defined in the use-case page's own frontmatter (automation: block). The sync script reads those pages directly — no separate _data/ file to maintain. - Remove _data/use-case-automations.yaml - Add automation: frontmatter to 4 use-case pages (vulnerability- remediation, code-review, incident-triage, dependency-upgrades) - Rewrite sync script to parse MDX frontmatter and generate the examples page cards + Automate This sections from it - Simplify workflow triggers (no more YAML data path) Adding a new use-case automation: 1. Add automation: block to the use-case page's frontmatter 2. Add BEGIN/END:automate-this markers where the section should go 3. Run: python .github/scripts/sync_use_case_automations.py 4. Commit the updated files — CI validates on every PR Co-authored-by: openhands --- .github/scripts/sync_use_case_automations.py | 173 +++++++++--------- .../workflows/sync-use-case-automations.yml | 7 - _data/use-case-automations.yaml | 101 ---------- openhands/usage/automations/examples.mdx | 74 ++++---- openhands/usage/use-cases/code-review.mdx | 23 ++- .../usage/use-cases/dependency-upgrades.mdx | 23 ++- openhands/usage/use-cases/incident-triage.mdx | 22 ++- .../use-cases/vulnerability-remediation.mdx | 25 ++- 8 files changed, 214 insertions(+), 234 deletions(-) delete mode 100644 _data/use-case-automations.yaml diff --git a/.github/scripts/sync_use_case_automations.py b/.github/scripts/sync_use_case_automations.py index f3ea5c976..7fda3bd2d 100644 --- a/.github/scripts/sync_use_case_automations.py +++ b/.github/scripts/sync_use_case_automations.py @@ -1,19 +1,27 @@ #!/usr/bin/env python3 """ -Sync use-case automation cards across documentation pages. +Sync use-case automation cards to the automation examples page. -Reads ``_data/use-case-automations.yaml`` (the single source of truth) and -regenerates the marked sections in: +Each use-case page under ``openhands/usage/use-cases/`` is the **source of +truth**. If a page's YAML frontmatter contains an ``automation:`` block, the +script treats it as an automation-enabled use case and: -* ``openhands/usage/automations/examples.mdx`` — card grid + Tabs per use case -* ``openhands/usage/use-cases/.mdx`` — "Automate This" section +1. Generates the "Use Case Automations" card grid + Tabs section in + ``openhands/usage/automations/examples.mdx`` (between markers). +2. Generates the "Automate This" section in the use-case page itself + (between markers). -The script replaces content between marker comments: - {/* BEGIN: ... */} … {/* END: */} +Marker format (JSX comments, ignored by Mintlify): + {/* BEGIN:use-case-automations */} … {/* END:use-case-automations */} + {/* BEGIN:automate-this */} … {/* END:automate-this */} + +Usage: + python .github/scripts/sync_use_case_automations.py # write mode + python .github/scripts/sync_use_case_automations.py --check # CI check Exit codes: - 0 — all files are in sync (or were updated with --write) - 1 — files are out of sync (CI check mode) + 0 — all files are in sync (or were updated in write mode) + 1 — files are out of sync (check mode) """ from __future__ import annotations @@ -27,21 +35,33 @@ import yaml REPO_ROOT = Path(__file__).resolve().parents[2] -DATA_FILE = REPO_ROOT / "_data" / "use-case-automations.yaml" EXAMPLES_PAGE = REPO_ROOT / "openhands" / "usage" / "automations" / "examples.mdx" USE_CASES_DIR = REPO_ROOT / "openhands" / "usage" / "use-cases" -BEGIN_RE = re.compile( - r"\{/\*\s*BEGIN:([\w-]+)\s*(?:—[^*]*)?\*/\}" -) -END_RE = re.compile( - r"\{/\*\s*END:([\w-]+)\s*\*/\}" -) +# Frontmatter delimiters +FRONTMATTER_RE = re.compile(r"\A---\n(.*?)\n---", re.DOTALL) + + +# ── Frontmatter parsing ────────────────────────────────────────────── +def parse_frontmatter(text: str) -> dict: + """Extract YAML frontmatter from an MDX file.""" + m = FRONTMATTER_RE.match(text) + if not m: + return {} + return yaml.safe_load(m.group(1)) or {} -def load_data() -> list[dict]: - with open(DATA_FILE) as f: - return yaml.safe_load(f)["use_cases"] + +def collect_use_cases() -> list[tuple[str, dict]]: + """Return (slug, automation_dict) for every use-case with automation metadata.""" + results: list[tuple[str, dict]] = [] + for page in sorted(USE_CASES_DIR.glob("*.mdx")): + if page.name == "overview.mdx": + continue + fm = parse_frontmatter(page.read_text()) + if "automation" in fm: + results.append((page.stem, fm["automation"])) + return results # ── Generators ──────────────────────────────────────────────────────── @@ -51,13 +71,12 @@ def _indent(text: str, n: int = 4) -> str: def _prompt_block(prompt: str, indent: int = 4) -> str: - """Wrap a prompt string in a fenced code block, indented.""" lines = prompt.rstrip("\n").split("\n") block = "```\n" + "\n".join(lines) + "\n```" return _indent(block, indent) -def generate_examples_section(use_cases: list[dict]) -> str: +def generate_examples_section(use_cases: list[tuple[str, dict]]) -> str: """Generate the ``use-case-automations`` block for *examples.mdx*.""" parts: list[str] = [] @@ -72,43 +91,41 @@ def generate_examples_section(use_cases: list[dict]) -> str: "" ) - # Cards - for uc in use_cases: + for slug, auto in use_cases: parts.append( f' \n' - f' {uc["card_description"]}\n' + f' {auto["card_description"]}\n' f' ' ) parts.append("") - # Tabs per use case - for uc in use_cases: - parts.append(f'\n### {uc["title"]}') + for slug, auto in use_cases: + parts.append(f'\n### {auto["card_title"]}') parts.append("") parts.append("") parts.append(' ') - parts.append(_prompt_block(uc["automation_prompt"])) + parts.append(_prompt_block(auto["prompt"])) parts.append(" ") - parts.append(f' ') - parts.append(f' {uc["alt_tab_body"]}') + parts.append(f' ') + parts.append(f' {auto["alt_tab_body"]}') parts.append(" ") parts.append("") return "\n".join(parts) -def generate_automate_this(uc: dict) -> str: +def generate_automate_this(auto: dict) -> str: """Generate the ``automate-this`` block for a single use-case page.""" - prompt = uc["automation_prompt"].rstrip("\n") + prompt = auto["prompt"].rstrip("\n") return ( f"## Automate This\n" f"\n" - f'{uc["use_case_intro"]}\n' + f'{auto["intro"]}\n' f"\n" f"```\n" f"{prompt}\n" @@ -124,37 +141,37 @@ def generate_automate_this(uc: dict) -> str: # ── Marker replacement ─────────────────────────────────────────────── -def replace_marker_section( - content: str, marker: str, new_body: str -) -> str: +def replace_marker_section(content: str, marker: str, new_body: str) -> str: """Replace everything between BEGIN: and END:.""" - begin_pattern = re.compile( + begin_pat = re.compile( rf"\{{/\*\s*BEGIN:{re.escape(marker)}\s*(?:—[^*]*)?\*/\}}" ) - end_pattern = re.compile( + end_pat = re.compile( rf"\{{/\*\s*END:{re.escape(marker)}\s*\*/\}}" ) - begin_match = begin_pattern.search(content) - end_match = end_pattern.search(content) - - if not begin_match or not end_match: - return content # markers not found — skip + begin_m = begin_pat.search(content) + end_m = end_pat.search(content) - begin_tag = begin_match.group(0) - end_tag = end_match.group(0) + if not begin_m or not end_m: + return content - before = content[: begin_match.start()] - after = content[end_match.end() :] - - return f"{before}{begin_tag}\n\n{new_body}\n\n{end_tag}{after}" + return ( + content[: begin_m.start()] + + begin_m.group(0) + + "\n\n" + + new_body + + "\n\n" + + end_m.group(0) + + content[end_m.end() :] + ) # ── Main ────────────────────────────────────────────────────────────── def main() -> int: parser = argparse.ArgumentParser( - description="Sync use-case automation cards from YAML data to MDX pages." + description="Sync use-case automation cards to the examples page." ) parser.add_argument( "--check", @@ -163,10 +180,14 @@ def main() -> int: ) args = parser.parse_args() - use_cases = load_data() + use_cases = collect_use_cases() + if not use_cases: + print("No use-case pages with automation frontmatter found.") + return 0 + diffs: list[str] = [] - # 1. Update examples.mdx + # 1. Regenerate the examples page card section original = EXAMPLES_PAGE.read_text() generated = generate_examples_section(use_cases) updated = replace_marker_section(original, "use-case-automations", generated) @@ -177,43 +198,26 @@ def main() -> int: EXAMPLES_PAGE.write_text(updated) print(f" ✏️ Updated {EXAMPLES_PAGE.relative_to(REPO_ROOT)}") - # 2. Update individual use-case pages - for uc in use_cases: - page = USE_CASES_DIR / f'{uc["slug"]}.mdx' - if not page.exists(): - print(f" ⚠️ Use-case page not found: {page.relative_to(REPO_ROOT)}") - diffs.append(str(page.relative_to(REPO_ROOT)) + " (missing)") - continue - + # 2. Regenerate the "Automate This" section in each use-case page + for slug, auto in use_cases: + page = USE_CASES_DIR / f"{slug}.mdx" original = page.read_text() - generated = generate_automate_this(uc) + generated = generate_automate_this(auto) updated = replace_marker_section(original, "automate-this", generated) if updated != original: - diffs.append(str(page.relative_to(REPO_ROOT))) + rel = str(page.relative_to(REPO_ROOT)) + diffs.append(rel) if not args.check: page.write_text(updated) - print(f" ✏️ Updated {page.relative_to(REPO_ROOT)}") - - # 3. Check for use-case pages without automation entries - existing_slugs = {uc["slug"] for uc in use_cases} - for page in sorted(USE_CASES_DIR.glob("*.mdx")): - if page.name == "overview.mdx": - continue - slug = page.stem - if slug not in existing_slugs: - content = page.read_text() - if BEGIN_RE.search(content): - # Has markers but no YAML entry — stale - print( - f" ⚠️ {page.relative_to(REPO_ROOT)} has automation markers " - f"but no entry in {DATA_FILE.relative_to(REPO_ROOT)}" - ) + print(f" ✏️ Updated {rel}") if diffs: if args.check: - print("\n❌ Files are out of sync with " - f"{DATA_FILE.relative_to(REPO_ROOT)}:") + print( + "\n❌ The automation examples page is out of sync with " + "use-case frontmatter:" + ) for d in diffs: print(f" - {d}") print( @@ -221,8 +225,7 @@ def main() -> int: "Then commit the updated files." ) return 1 - else: - print(f"\n✅ Updated {len(diffs)} file(s).") + print(f"\n✅ Updated {len(diffs)} file(s).") else: print("✅ All files are in sync.") diff --git a/.github/workflows/sync-use-case-automations.yml b/.github/workflows/sync-use-case-automations.yml index 69ccb7163..1e71fcd8f 100644 --- a/.github/workflows/sync-use-case-automations.yml +++ b/.github/workflows/sync-use-case-automations.yml @@ -5,17 +5,10 @@ on: branches: - '**' paths: - - '_data/use-case-automations.yaml' - 'openhands/usage/automations/examples.mdx' - 'openhands/usage/use-cases/**' - '.github/scripts/sync_use_case_automations.py' - '.github/workflows/sync-use-case-automations.yml' - push: - branches: - - main - paths: - - '_data/use-case-automations.yaml' - - '.github/scripts/sync_use_case_automations.py' permissions: contents: read diff --git a/_data/use-case-automations.yaml b/_data/use-case-automations.yaml deleted file mode 100644 index a1a101333..000000000 --- a/_data/use-case-automations.yaml +++ /dev/null @@ -1,101 +0,0 @@ -# Single source of truth for use-case → automation mappings. -# -# A CI workflow (`sync-use-case-automations.yml`) reads this file and -# regenerates the auto-generated sections in: -# - openhands/usage/automations/examples.mdx (card grid + Tabs per use case) -# - openhands/usage/use-cases/.mdx ("Automate This" section) -# -# To add a new use case automation: -# 1. Add an entry below. -# 2. Run: python .github/scripts/sync_use_case_automations.py -# 3. Commit the updated MDX files together with this YAML change. - -use_cases: - - slug: vulnerability-remediation - title: Vulnerability Scan - icon: shield-halved - card_description: >- - Scan dependencies for known CVEs and post a report. Pairs with the - [vulnerability-remediation plugin](https://github.com/OpenHands/extensions/tree/main/plugins/vulnerability-remediation). - use_case_intro: >- - Run vulnerability scans on a schedule with an OpenHands automation. - Copy this prompt into a conversation: - automation_prompt: | - Create an automation called "Security Scan" that runs daily at 3 AM. - - It should run a security audit: - 1. Check for known vulnerabilities in dependencies - 2. Scan for hardcoded secrets or API keys - 3. Look for common security misconfigurations - - Create a detailed report and alert #security if any high or critical issues are found. - alt_tab_title: Plugin - alt_tab_body: >- - Use the [vulnerability-remediation plugin](https://github.com/OpenHands/extensions/tree/main/plugins/vulnerability-remediation) - for a more thorough scan with automated fix PRs. See the - [full use case guide](/openhands/usage/use-cases/vulnerability-remediation). - - - slug: code-review - title: Automated Code Review - icon: code-pull-request - card_description: >- - Review PRs automatically on every push. Pairs with the - [pr-review plugin](https://github.com/OpenHands/extensions/tree/main/plugins/pr-review). - use_case_intro: >- - Schedule daily code reviews with an OpenHands automation. - Copy this prompt into a conversation: - automation_prompt: | - Create an automation called "Daily Code Review" that runs every weekday at 9 AM. - - It should: - 1. Find all open PRs that have no reviews yet - 2. For each PR, review the diff for bugs, style issues, and security concerns - 3. Post a summary of findings as a comment on each PR - alt_tab_title: Plugin - alt_tab_body: >- - Use the [pr-review plugin](https://github.com/OpenHands/extensions/tree/main/plugins/pr-review) - for inline review comments on every PR. See the - [full use case guide](/openhands/usage/use-cases/code-review). - - - slug: incident-triage - title: Incident Monitoring - icon: triangle-exclamation - card_description: >- - Monitor APIs, analyze errors, and alert your team. Pairs with the - [Datadog debugging workflow](https://github.com/OpenHands/software-agent-sdk/tree/main/examples/03_github_workflows/04_datadog_debugging). - use_case_intro: >- - Set up continuous health monitoring with an OpenHands automation. - Copy this prompt into a conversation: - automation_prompt: | - Create an automation called "API Health Monitor" that runs every 30 minutes. - - It should check https://api.example.com/health and: - - If the response is not 200 OK, send an alert to #alerts with the status code and response body - - If healthy, just log success without alerting anyone - alt_tab_title: Plugin - alt_tab_body: >- - Use the [Datadog debugging workflow](https://github.com/OpenHands/software-agent-sdk/tree/main/examples/03_github_workflows/04_datadog_debugging) - for deeper error analysis with Datadog integration. See the - [full use case guide](/openhands/usage/use-cases/incident-triage). - - - slug: dependency-upgrades - title: Dependency Upgrades - icon: arrow-up-right-dots - card_description: >- - Check for outdated packages weekly and report available updates. - use_case_intro: >- - Schedule weekly dependency checks with an OpenHands automation. - Copy this prompt into a conversation: - automation_prompt: | - Create an automation called "Dependency Checker" that runs every Monday at 8 AM. - - It should: - 1. Scan all package.json and requirements.txt files - 2. Check for outdated dependencies - 3. Create a report listing packages with available updates (grouped by major/minor/patch) - 4. Post the report to #engineering - alt_tab_title: Learn More - alt_tab_body: >- - See the [full use case guide](/openhands/usage/use-cases/dependency-upgrades) - for strategies on handling breaking changes, planning major upgrades, - and validating after updates. diff --git a/openhands/usage/automations/examples.mdx b/openhands/usage/automations/examples.mdx index 295fb5039..6f70dc7e2 100644 --- a/openhands/usage/automations/examples.mdx +++ b/openhands/usage/automations/examples.mdx @@ -13,20 +13,13 @@ Browse automation templates below. Each card includes a ready-to-use prompt—ju These examples reference services like Slack and GitHub. Git providers you logged in with are automatically available, but other services like Slack require [MCP configuration](/openhands/usage/settings/mcp-settings). -{/* BEGIN:use-case-automations — auto-generated from _data/use-case-automations.yaml */} +{/* BEGIN:use-case-automations — auto-generated from use-case frontmatter */} ## Use Case Automations These automations correspond to documented [use cases](/openhands/usage/use-cases/overview). Each card links to the full use case guide, the relevant plugin or SDK example, and a prompt you can copy directly. - - Scan dependencies for known CVEs and post a report. Pairs with the [vulnerability-remediation plugin](https://github.com/OpenHands/extensions/tree/main/plugins/vulnerability-remediation). - Review PRs automatically on every push. Pairs with the [pr-review plugin](https://github.com/OpenHands/extensions/tree/main/plugins/pr-review). + + Check for outdated packages weekly and report available updates. + - Check for outdated packages weekly and report available updates. + Scan dependencies for known CVEs and post a report. Pairs with the [vulnerability-remediation plugin](https://github.com/OpenHands/extensions/tree/main/plugins/vulnerability-remediation). -### Vulnerability Scan +### Automated Code Review ``` - Create an automation called "Security Scan" that runs daily at 3 AM. - - It should run a security audit: - 1. Check for known vulnerabilities in dependencies - 2. Scan for hardcoded secrets or API keys - 3. Look for common security misconfigurations + Create an automation called "Daily Code Review" that runs every weekday at 9 AM. - Create a detailed report and alert #security if any high or critical issues are found. + It should: + 1. Find all open PRs that have no reviews yet + 2. For each PR, review the diff for bugs, style issues, and security concerns + 3. Post a summary of findings as a comment on each PR ``` - Use the [vulnerability-remediation plugin](https://github.com/OpenHands/extensions/tree/main/plugins/vulnerability-remediation) for a more thorough scan with automated fix PRs. See the [full use case guide](/openhands/usage/use-cases/vulnerability-remediation). + Use the [pr-review plugin](https://github.com/OpenHands/extensions/tree/main/plugins/pr-review) for inline review comments on every PR. See the [full use case guide](/openhands/usage/use-cases/code-review). -### Automated Code Review +### Dependency Upgrades ``` - Create an automation called "Daily Code Review" that runs every weekday at 9 AM. + Create an automation called "Dependency Checker" that runs every Monday at 8 AM. It should: - 1. Find all open PRs that have no reviews yet - 2. For each PR, review the diff for bugs, style issues, and security concerns - 3. Post a summary of findings as a comment on each PR + 1. Scan all package.json and requirements.txt files + 2. Check for outdated dependencies + 3. Create a report listing packages with available updates (grouped by major/minor/patch) + 4. Post the report to #engineering ``` - - Use the [pr-review plugin](https://github.com/OpenHands/extensions/tree/main/plugins/pr-review) for inline review comments on every PR. See the [full use case guide](/openhands/usage/use-cases/code-review). + + See the [full use case guide](/openhands/usage/use-cases/dependency-upgrades) for strategies on handling breaking changes, planning major upgrades, and validating after updates. @@ -105,22 +104,23 @@ These automations correspond to documented [use cases](/openhands/usage/use-case -### Dependency Upgrades +### Vulnerability Scan ``` - Create an automation called "Dependency Checker" that runs every Monday at 8 AM. + Create an automation called "Security Scan" that runs daily at 3 AM. - It should: - 1. Scan all package.json and requirements.txt files - 2. Check for outdated dependencies - 3. Create a report listing packages with available updates (grouped by major/minor/patch) - 4. Post the report to #engineering + It should run a security audit: + 1. Check for known vulnerabilities in dependencies + 2. Scan for hardcoded secrets or API keys + 3. Look for common security misconfigurations + + Create a detailed report and alert #security if any high or critical issues are found. ``` - - See the [full use case guide](/openhands/usage/use-cases/dependency-upgrades) for strategies on handling breaking changes, planning major upgrades, and validating after updates. + + Use the [vulnerability-remediation plugin](https://github.com/OpenHands/extensions/tree/main/plugins/vulnerability-remediation) for a more thorough scan with automated fix PRs. See the [full use case guide](/openhands/usage/use-cases/vulnerability-remediation). diff --git a/openhands/usage/use-cases/code-review.mdx b/openhands/usage/use-cases/code-review.mdx index 7617ac2d2..0e58ef009 100644 --- a/openhands/usage/use-cases/code-review.mdx +++ b/openhands/usage/use-cases/code-review.mdx @@ -1,6 +1,27 @@ --- title: Automated Code Review description: Set up automated PR reviews using OpenHands and the Software Agent SDK +automation: + card_title: Automated Code Review + icon: code-pull-request + card_description: >- + Review PRs automatically on every push. Pairs with the + [pr-review plugin](https://github.com/OpenHands/extensions/tree/main/plugins/pr-review). + intro: >- + Schedule daily code reviews with an OpenHands automation. + Copy this prompt into a conversation: + prompt: | + Create an automation called "Daily Code Review" that runs every weekday at 9 AM. + + It should: + 1. Find all open PRs that have no reviews yet + 2. For each PR, review the diff for bugs, style issues, and security concerns + 3. Post a summary of findings as a comment on each PR + alt_tab_title: Plugin + alt_tab_body: >- + Use the [pr-review plugin](https://github.com/OpenHands/extensions/tree/main/plugins/pr-review) + for inline review comments on every PR. See the + [full use case guide](/openhands/usage/use-cases/code-review). --- -{/* BEGIN:automate-this — auto-generated from _data/use-case-automations.yaml */} +{/* BEGIN:automate-this — auto-generated from frontmatter */} ## Automate This diff --git a/openhands/usage/use-cases/dependency-upgrades.mdx b/openhands/usage/use-cases/dependency-upgrades.mdx index 16d7dd234..47c9885a2 100644 --- a/openhands/usage/use-cases/dependency-upgrades.mdx +++ b/openhands/usage/use-cases/dependency-upgrades.mdx @@ -1,6 +1,27 @@ --- title: Dependency Upgrades description: Automating dependency updates and upgrades with OpenHands +automation: + card_title: Dependency Upgrades + icon: arrow-up-right-dots + card_description: >- + Check for outdated packages weekly and report available updates. + intro: >- + Schedule weekly dependency checks with an OpenHands automation. + Copy this prompt into a conversation: + prompt: | + Create an automation called "Dependency Checker" that runs every Monday at 8 AM. + + It should: + 1. Scan all package.json and requirements.txt files + 2. Check for outdated dependencies + 3. Create a report listing packages with available updates (grouped by major/minor/patch) + 4. Post the report to #engineering + alt_tab_title: Learn More + alt_tab_body: >- + See the [full use case guide](/openhands/usage/use-cases/dependency-upgrades) + for strategies on handling breaking changes, planning major upgrades, + and validating after updates. --- Keeping dependencies up to date is essential for security, performance, and access to new features. OpenHands can help you identify outdated dependencies, plan upgrades, handle breaking changes, and validate that your application still works after updates. @@ -277,7 +298,7 @@ Create an upgrade plan that handles all these together, addressing breaking changes in the correct order. ``` -{/* BEGIN:automate-this — auto-generated from _data/use-case-automations.yaml */} +{/* BEGIN:automate-this — auto-generated from frontmatter */} ## Automate This diff --git a/openhands/usage/use-cases/incident-triage.mdx b/openhands/usage/use-cases/incident-triage.mdx index c362c9c1a..039ac3dac 100644 --- a/openhands/usage/use-cases/incident-triage.mdx +++ b/openhands/usage/use-cases/incident-triage.mdx @@ -1,6 +1,26 @@ --- title: Incident Triage description: Using OpenHands to investigate and resolve production incidents +automation: + card_title: Incident Monitoring + icon: triangle-exclamation + card_description: >- + Monitor APIs, analyze errors, and alert your team. Pairs with the + [Datadog debugging workflow](https://github.com/OpenHands/software-agent-sdk/tree/main/examples/03_github_workflows/04_datadog_debugging). + intro: >- + Set up continuous health monitoring with an OpenHands automation. + Copy this prompt into a conversation: + prompt: | + Create an automation called "API Health Monitor" that runs every 30 minutes. + + It should check https://api.example.com/health and: + - If the response is not 200 OK, send an alert to #alerts with the status code and response body + - If healthy, just log success without alerting anyone + alt_tab_title: Plugin + alt_tab_body: >- + Use the [Datadog debugging workflow](https://github.com/OpenHands/software-agent-sdk/tree/main/examples/03_github_workflows/04_datadog_debugging) + for deeper error analysis with Datadog integration. See the + [full use case guide](/openhands/usage/use-cases/incident-triage). --- -{/* BEGIN:automate-this — auto-generated from _data/use-case-automations.yaml */} +{/* BEGIN:automate-this — auto-generated from frontmatter */} ## Automate This diff --git a/openhands/usage/use-cases/vulnerability-remediation.mdx b/openhands/usage/use-cases/vulnerability-remediation.mdx index 31b55c40e..e308b4ec0 100644 --- a/openhands/usage/use-cases/vulnerability-remediation.mdx +++ b/openhands/usage/use-cases/vulnerability-remediation.mdx @@ -1,6 +1,29 @@ --- title: Vulnerability Remediation description: Using OpenHands to identify and fix security vulnerabilities in your codebase +automation: + card_title: Vulnerability Scan + icon: shield-halved + card_description: >- + Scan dependencies for known CVEs and post a report. Pairs with the + [vulnerability-remediation plugin](https://github.com/OpenHands/extensions/tree/main/plugins/vulnerability-remediation). + intro: >- + Run vulnerability scans on a schedule with an OpenHands automation. + Copy this prompt into a conversation: + prompt: | + Create an automation called "Security Scan" that runs daily at 3 AM. + + It should run a security audit: + 1. Check for known vulnerabilities in dependencies + 2. Scan for hardcoded secrets or API keys + 3. Look for common security misconfigurations + + Create a detailed report and alert #security if any high or critical issues are found. + alt_tab_title: Plugin + alt_tab_body: >- + Use the [vulnerability-remediation plugin](https://github.com/OpenHands/extensions/tree/main/plugins/vulnerability-remediation) + for a more thorough scan with automated fix PRs. See the + [full use case guide](/openhands/usage/use-cases/vulnerability-remediation). --- Date: Tue, 14 Apr 2026 15:05:22 +0000 Subject: [PATCH 4/8] fix: remove duplicated Automate This content, link back to examples page MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The Automate This sections were duplicating the prompt already defined in frontmatter. Now use-case pages just have a simple card linking back to the automation examples page (with an anchor to the specific use case). The prompt content lives in one place only — the frontmatter — and the sync script copies it to examples.mdx. - Remove generated Automate This blocks and markers from use-case pages - Replace with a static Card linking to examples page anchor - Remove unused intro field from frontmatter - Simplify sync script to only generate the examples page Co-authored-by: openhands --- .github/scripts/sync_use_case_automations.py | 91 ++++--------------- openhands/usage/use-cases/code-review.mdx | 22 +---- .../usage/use-cases/dependency-upgrades.mdx | 23 +---- openhands/usage/use-cases/incident-triage.mdx | 21 +---- .../use-cases/vulnerability-remediation.mdx | 24 +---- 5 files changed, 28 insertions(+), 153 deletions(-) diff --git a/.github/scripts/sync_use_case_automations.py b/.github/scripts/sync_use_case_automations.py index 7fda3bd2d..0c09adb16 100644 --- a/.github/scripts/sync_use_case_automations.py +++ b/.github/scripts/sync_use_case_automations.py @@ -4,24 +4,19 @@ Each use-case page under ``openhands/usage/use-cases/`` is the **source of truth**. If a page's YAML frontmatter contains an ``automation:`` block, the -script treats it as an automation-enabled use case and: +script copies that content into the "Use Case Automations" section of +``openhands/usage/automations/examples.mdx``. -1. Generates the "Use Case Automations" card grid + Tabs section in - ``openhands/usage/automations/examples.mdx`` (between markers). -2. Generates the "Automate This" section in the use-case page itself - (between markers). - -Marker format (JSX comments, ignored by Mintlify): +The generated section lives between marker comments in examples.mdx: {/* BEGIN:use-case-automations */} … {/* END:use-case-automations */} - {/* BEGIN:automate-this */} … {/* END:automate-this */} Usage: python .github/scripts/sync_use_case_automations.py # write mode python .github/scripts/sync_use_case_automations.py --check # CI check Exit codes: - 0 — all files are in sync (or were updated in write mode) - 1 — files are out of sync (check mode) + 0 — examples page is in sync (or was updated in write mode) + 1 — examples page is out of sync (check mode) """ from __future__ import annotations @@ -38,14 +33,12 @@ EXAMPLES_PAGE = REPO_ROOT / "openhands" / "usage" / "automations" / "examples.mdx" USE_CASES_DIR = REPO_ROOT / "openhands" / "usage" / "use-cases" -# Frontmatter delimiters FRONTMATTER_RE = re.compile(r"\A---\n(.*?)\n---", re.DOTALL) # ── Frontmatter parsing ────────────────────────────────────────────── def parse_frontmatter(text: str) -> dict: - """Extract YAML frontmatter from an MDX file.""" m = FRONTMATTER_RE.match(text) if not m: return {} @@ -64,7 +57,7 @@ def collect_use_cases() -> list[tuple[str, dict]]: return results -# ── Generators ──────────────────────────────────────────────────────── +# ── Generator ───────────────────────────────────────────────────────── def _indent(text: str, n: int = 4) -> str: return textwrap.indent(text, " " * n) @@ -119,26 +112,6 @@ def generate_examples_section(use_cases: list[tuple[str, dict]]) -> str: return "\n".join(parts) -def generate_automate_this(auto: dict) -> str: - """Generate the ``automate-this`` block for a single use-case page.""" - prompt = auto["prompt"].rstrip("\n") - return ( - f"## Automate This\n" - f"\n" - f'{auto["intro"]}\n' - f"\n" - f"```\n" - f"{prompt}\n" - f"```\n" - f"\n" - f'\n' - f" Browse all automation examples, including vulnerability scanning, " - f"code review, monitoring, and more.\n" - f"" - ) - - # ── Marker replacement ─────────────────────────────────────────────── def replace_marker_section(content: str, marker: str, new_body: str) -> str: @@ -185,50 +158,26 @@ def main() -> int: print("No use-case pages with automation frontmatter found.") return 0 - diffs: list[str] = [] - - # 1. Regenerate the examples page card section original = EXAMPLES_PAGE.read_text() generated = generate_examples_section(use_cases) updated = replace_marker_section(original, "use-case-automations", generated) - if updated != original: - diffs.append(str(EXAMPLES_PAGE.relative_to(REPO_ROOT))) - if not args.check: - EXAMPLES_PAGE.write_text(updated) - print(f" ✏️ Updated {EXAMPLES_PAGE.relative_to(REPO_ROOT)}") + if updated == original: + print("✅ Automation examples page is in sync.") + return 0 - # 2. Regenerate the "Automate This" section in each use-case page - for slug, auto in use_cases: - page = USE_CASES_DIR / f"{slug}.mdx" - original = page.read_text() - generated = generate_automate_this(auto) - updated = replace_marker_section(original, "automate-this", generated) - - if updated != original: - rel = str(page.relative_to(REPO_ROOT)) - diffs.append(rel) - if not args.check: - page.write_text(updated) - print(f" ✏️ Updated {rel}") - - if diffs: - if args.check: - print( - "\n❌ The automation examples page is out of sync with " - "use-case frontmatter:" - ) - for d in diffs: - print(f" - {d}") - print( - "\nRun: python .github/scripts/sync_use_case_automations.py\n" - "Then commit the updated files." - ) - return 1 - print(f"\n✅ Updated {len(diffs)} file(s).") - else: - print("✅ All files are in sync.") + if args.check: + print( + "❌ openhands/usage/automations/examples.mdx is out of sync " + "with use-case frontmatter.\n" + "\n" + "Run: python .github/scripts/sync_use_case_automations.py\n" + "Then commit the updated file." + ) + return 1 + EXAMPLES_PAGE.write_text(updated) + print(f"✅ Updated {EXAMPLES_PAGE.relative_to(REPO_ROOT)}") return 0 diff --git a/openhands/usage/use-cases/code-review.mdx b/openhands/usage/use-cases/code-review.mdx index 0e58ef009..b51ba3053 100644 --- a/openhands/usage/use-cases/code-review.mdx +++ b/openhands/usage/use-cases/code-review.mdx @@ -7,9 +7,6 @@ automation: card_description: >- Review PRs automatically on every push. Pairs with the [pr-review plugin](https://github.com/OpenHands/extensions/tree/main/plugins/pr-review). - intro: >- - Schedule daily code reviews with an OpenHands automation. - Copy this prompt into a conversation: prompt: | Create an automation called "Daily Code Review" that runs every weekday at 9 AM. @@ -287,27 +284,12 @@ See real automated reviews in action on the OpenHands Software Agent SDK reposit -{/* BEGIN:automate-this — auto-generated from frontmatter */} - ## Automate This -Schedule daily code reviews with an OpenHands automation. Copy this prompt into a conversation: - -``` -Create an automation called "Daily Code Review" that runs every weekday at 9 AM. - -It should: -1. Find all open PRs that have no reviews yet -2. For each PR, review the diff for bugs, style issues, and security concerns -3. Post a summary of findings as a comment on each PR -``` - - - Browse all automation examples, including vulnerability scanning, code review, monitoring, and more. + + Run this use case as a scheduled automation — copy a ready-to-use prompt from the Automation Examples page. -{/* END:automate-this */} - ## Related Resources - [PR Review Workflow Reference](https://github.com/OpenHands/software-agent-sdk/tree/main/examples/03_github_workflows/02_pr_review) - Full workflow example and agent script diff --git a/openhands/usage/use-cases/dependency-upgrades.mdx b/openhands/usage/use-cases/dependency-upgrades.mdx index 47c9885a2..f2061f598 100644 --- a/openhands/usage/use-cases/dependency-upgrades.mdx +++ b/openhands/usage/use-cases/dependency-upgrades.mdx @@ -6,9 +6,6 @@ automation: icon: arrow-up-right-dots card_description: >- Check for outdated packages weekly and report available updates. - intro: >- - Schedule weekly dependency checks with an OpenHands automation. - Copy this prompt into a conversation: prompt: | Create an automation called "Dependency Checker" that runs every Monday at 8 AM. @@ -298,28 +295,12 @@ Create an upgrade plan that handles all these together, addressing breaking changes in the correct order. ``` -{/* BEGIN:automate-this — auto-generated from frontmatter */} - ## Automate This -Schedule weekly dependency checks with an OpenHands automation. Copy this prompt into a conversation: - -``` -Create an automation called "Dependency Checker" that runs every Monday at 8 AM. - -It should: -1. Scan all package.json and requirements.txt files -2. Check for outdated dependencies -3. Create a report listing packages with available updates (grouped by major/minor/patch) -4. Post the report to #engineering -``` - - - Browse all automation examples, including vulnerability scanning, code review, monitoring, and more. + + Run this use case as a scheduled automation — copy a ready-to-use prompt from the Automation Examples page. -{/* END:automate-this */} - ## Related Resources - [Vulnerability Remediation](/openhands/usage/use-cases/vulnerability-remediation) - Fix security vulnerabilities diff --git a/openhands/usage/use-cases/incident-triage.mdx b/openhands/usage/use-cases/incident-triage.mdx index 039ac3dac..9091333ef 100644 --- a/openhands/usage/use-cases/incident-triage.mdx +++ b/openhands/usage/use-cases/incident-triage.mdx @@ -7,9 +7,6 @@ automation: card_description: >- Monitor APIs, analyze errors, and alert your team. Pairs with the [Datadog debugging workflow](https://github.com/OpenHands/software-agent-sdk/tree/main/examples/03_github_workflows/04_datadog_debugging). - intro: >- - Set up continuous health monitoring with an OpenHands automation. - Copy this prompt into a conversation: prompt: | Create an automation called "API Health Monitor" that runs every 30 minutes. @@ -277,26 +274,12 @@ Avoid these common incident response mistakes: For production incidents, always follow your organization's incident response procedures. OpenHands is a tool to assist your investigation, not a replacement for proper incident management. -{/* BEGIN:automate-this — auto-generated from frontmatter */} - ## Automate This -Set up continuous health monitoring with an OpenHands automation. Copy this prompt into a conversation: - -``` -Create an automation called "API Health Monitor" that runs every 30 minutes. - -It should check https://api.example.com/health and: -- If the response is not 200 OK, send an alert to #alerts with the status code and response body -- If healthy, just log success without alerting anyone -``` - - - Browse all automation examples, including vulnerability scanning, code review, monitoring, and more. + + Run this use case as a scheduled automation — copy a ready-to-use prompt from the Automation Examples page. -{/* END:automate-this */} - ## Related Resources - [OpenHands SDK Repository](https://github.com/OpenHands/software-agent-sdk) - Build custom AI agents diff --git a/openhands/usage/use-cases/vulnerability-remediation.mdx b/openhands/usage/use-cases/vulnerability-remediation.mdx index e308b4ec0..84b1f2d2b 100644 --- a/openhands/usage/use-cases/vulnerability-remediation.mdx +++ b/openhands/usage/use-cases/vulnerability-remediation.mdx @@ -7,9 +7,6 @@ automation: card_description: >- Scan dependencies for known CVEs and post a report. Pairs with the [vulnerability-remediation plugin](https://github.com/OpenHands/extensions/tree/main/plugins/vulnerability-remediation). - intro: >- - Run vulnerability scans on a schedule with an OpenHands automation. - Copy this prompt into a conversation: prompt: | Create an automation called "Security Scan" that runs daily at 3 AM. @@ -299,29 +296,12 @@ To build your own vulnerability remediation agent: As agent capabilities continue to evolve, an increasing number of repetitive and time-consuming security tasks can be automated, enabling developers to focus on higher-level design, innovation, and problem-solving rather than routine maintenance. -{/* BEGIN:automate-this — auto-generated from frontmatter */} - ## Automate This -Run vulnerability scans on a schedule with an OpenHands automation. Copy this prompt into a conversation: - -``` -Create an automation called "Security Scan" that runs daily at 3 AM. - -It should run a security audit: -1. Check for known vulnerabilities in dependencies -2. Scan for hardcoded secrets or API keys -3. Look for common security misconfigurations - -Create a detailed report and alert #security if any high or critical issues are found. -``` - - - Browse all automation examples, including vulnerability scanning, code review, monitoring, and more. + + Run this use case as a scheduled automation — copy a ready-to-use prompt from the Automation Examples page. -{/* END:automate-this */} - ## Related Resources - [Vulnerability Fixer Example](https://github.com/OpenHands/vulnerability-fixer) - Full implementation example From 08de15042713ae13fa5b849f9e769cd1c4cba8e3 Mon Sep 17 00:00:00 2001 From: openhands Date: Tue, 14 Apr 2026 15:14:03 +0000 Subject: [PATCH 5/8] fix: use-case pages own the full automation content, examples page is a card index MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Use-case pages are now the single source of truth: - Frontmatter has only card metadata (title, icon, short description) - Page body has the full 'Automate This' section with prompts, context, and plugin links — this is what users actually read and copy The automation examples page is just a card grid that links to each use-case page's #automate-this section. The sync script generates those cards from the frontmatter metadata. Co-authored-by: openhands --- .github/scripts/sync_use_case_automations.py | 36 ++------ openhands/usage/automations/examples.mdx | 90 ++----------------- openhands/usage/use-cases/code-review.mdx | 33 ++++--- .../usage/use-cases/dependency-upgrades.mdx | 28 +++--- openhands/usage/use-cases/incident-triage.mdx | 30 +++---- .../use-cases/vulnerability-remediation.mdx | 36 ++++---- 6 files changed, 75 insertions(+), 178 deletions(-) diff --git a/.github/scripts/sync_use_case_automations.py b/.github/scripts/sync_use_case_automations.py index 0c09adb16..21b4ea37e 100644 --- a/.github/scripts/sync_use_case_automations.py +++ b/.github/scripts/sync_use_case_automations.py @@ -24,7 +24,6 @@ import argparse import re import sys -import textwrap from pathlib import Path import yaml @@ -59,27 +58,20 @@ def collect_use_cases() -> list[tuple[str, dict]]: # ── Generator ───────────────────────────────────────────────────────── -def _indent(text: str, n: int = 4) -> str: - return textwrap.indent(text, " " * n) - - -def _prompt_block(prompt: str, indent: int = 4) -> str: - lines = prompt.rstrip("\n").split("\n") - block = "```\n" + "\n".join(lines) + "\n```" - return _indent(block, indent) - def generate_examples_section(use_cases: list[tuple[str, dict]]) -> str: - """Generate the ``use-case-automations`` block for *examples.mdx*.""" + """Generate the ``use-case-automations`` block for *examples.mdx*. + + Each card links to the "Automate This" section of the corresponding + use-case page, where the full prompt and instructions live. + """ parts: list[str] = [] parts.append( "## Use Case Automations\n" "\n" - "These automations correspond to documented " - "[use cases](/openhands/usage/use-cases/overview). " - "Each card links to the full use case guide, the relevant plugin " - "or SDK example, and a prompt you can copy directly.\n" + "Each use case has a ready-to-use automation prompt. " + "Click a card to see the full instructions.\n" "\n" "" ) @@ -89,7 +81,7 @@ def generate_examples_section(use_cases: list[tuple[str, dict]]) -> str: f' \n' f' {auto["card_description"]}\n' f' ' @@ -97,18 +89,6 @@ def generate_examples_section(use_cases: list[tuple[str, dict]]) -> str: parts.append("") - for slug, auto in use_cases: - parts.append(f'\n### {auto["card_title"]}') - parts.append("") - parts.append("") - parts.append(' ') - parts.append(_prompt_block(auto["prompt"])) - parts.append(" ") - parts.append(f' ') - parts.append(f' {auto["alt_tab_body"]}') - parts.append(" ") - parts.append("") - return "\n".join(parts) diff --git a/openhands/usage/automations/examples.mdx b/openhands/usage/automations/examples.mdx index 6f70dc7e2..d4350f1a5 100644 --- a/openhands/usage/automations/examples.mdx +++ b/openhands/usage/automations/examples.mdx @@ -17,113 +17,39 @@ These examples reference services like Slack and GitHub. Git providers you logge ## Use Case Automations -These automations correspond to documented [use cases](/openhands/usage/use-cases/overview). Each card links to the full use case guide, the relevant plugin or SDK example, and a prompt you can copy directly. +Each use case has a ready-to-use automation prompt. Click a card to see the full instructions. - Review PRs automatically on every push. Pairs with the [pr-review plugin](https://github.com/OpenHands/extensions/tree/main/plugins/pr-review). + Review open PRs daily for bugs, style issues, and security concerns. Check for outdated packages weekly and report available updates. - Monitor APIs, analyze errors, and alert your team. Pairs with the [Datadog debugging workflow](https://github.com/OpenHands/software-agent-sdk/tree/main/examples/03_github_workflows/04_datadog_debugging). + Monitor API health, analyze errors, and alert your team automatically. - Scan dependencies for known CVEs and post a report. Pairs with the [vulnerability-remediation plugin](https://github.com/OpenHands/extensions/tree/main/plugins/vulnerability-remediation). + Scan dependencies for known CVEs, find hardcoded secrets, and alert your team on a schedule. -### Automated Code Review - - - - ``` - Create an automation called "Daily Code Review" that runs every weekday at 9 AM. - - It should: - 1. Find all open PRs that have no reviews yet - 2. For each PR, review the diff for bugs, style issues, and security concerns - 3. Post a summary of findings as a comment on each PR - ``` - - - Use the [pr-review plugin](https://github.com/OpenHands/extensions/tree/main/plugins/pr-review) for inline review comments on every PR. See the [full use case guide](/openhands/usage/use-cases/code-review). - - - -### Dependency Upgrades - - - - ``` - Create an automation called "Dependency Checker" that runs every Monday at 8 AM. - - It should: - 1. Scan all package.json and requirements.txt files - 2. Check for outdated dependencies - 3. Create a report listing packages with available updates (grouped by major/minor/patch) - 4. Post the report to #engineering - ``` - - - See the [full use case guide](/openhands/usage/use-cases/dependency-upgrades) for strategies on handling breaking changes, planning major upgrades, and validating after updates. - - - -### Incident Monitoring - - - - ``` - Create an automation called "API Health Monitor" that runs every 30 minutes. - - It should check https://api.example.com/health and: - - If the response is not 200 OK, send an alert to #alerts with the status code and response body - - If healthy, just log success without alerting anyone - ``` - - - Use the [Datadog debugging workflow](https://github.com/OpenHands/software-agent-sdk/tree/main/examples/03_github_workflows/04_datadog_debugging) for deeper error analysis with Datadog integration. See the [full use case guide](/openhands/usage/use-cases/incident-triage). - - - -### Vulnerability Scan - - - - ``` - Create an automation called "Security Scan" that runs daily at 3 AM. - - It should run a security audit: - 1. Check for known vulnerabilities in dependencies - 2. Scan for hardcoded secrets or API keys - 3. Look for common security misconfigurations - - Create a detailed report and alert #security if any high or critical issues are found. - ``` - - - Use the [vulnerability-remediation plugin](https://github.com/OpenHands/extensions/tree/main/plugins/vulnerability-remediation) for a more thorough scan with automated fix PRs. See the [full use case guide](/openhands/usage/use-cases/vulnerability-remediation). - - - {/* END:use-case-automations */} --- diff --git a/openhands/usage/use-cases/code-review.mdx b/openhands/usage/use-cases/code-review.mdx index b51ba3053..e5939a96c 100644 --- a/openhands/usage/use-cases/code-review.mdx +++ b/openhands/usage/use-cases/code-review.mdx @@ -5,20 +5,7 @@ automation: card_title: Automated Code Review icon: code-pull-request card_description: >- - Review PRs automatically on every push. Pairs with the - [pr-review plugin](https://github.com/OpenHands/extensions/tree/main/plugins/pr-review). - prompt: | - Create an automation called "Daily Code Review" that runs every weekday at 9 AM. - - It should: - 1. Find all open PRs that have no reviews yet - 2. For each PR, review the diff for bugs, style issues, and security concerns - 3. Post a summary of findings as a comment on each PR - alt_tab_title: Plugin - alt_tab_body: >- - Use the [pr-review plugin](https://github.com/OpenHands/extensions/tree/main/plugins/pr-review) - for inline review comments on every PR. See the - [full use case guide](/openhands/usage/use-cases/code-review). + Review open PRs daily for bugs, style issues, and security concerns. --- - Run this use case as a scheduled automation — copy a ready-to-use prompt from the Automation Examples page. - +You can schedule daily code reviews using [OpenHands Automations](/openhands/usage/automations/overview). +Copy this prompt into a new conversation to set one up: + +``` +Create an automation called "Daily Code Review" that runs every weekday at 9 AM. + +It should: +1. Find all open PRs that have no reviews yet +2. For each PR, review the diff for bugs, style issues, and security concerns +3. Post a summary of findings as a comment on each PR +``` + +For inline review comments on every push, use the +[pr-review plugin](https://github.com/OpenHands/extensions/tree/main/plugins/pr-review) +as a GitHub Action instead. ## Related Resources diff --git a/openhands/usage/use-cases/dependency-upgrades.mdx b/openhands/usage/use-cases/dependency-upgrades.mdx index f2061f598..335282a64 100644 --- a/openhands/usage/use-cases/dependency-upgrades.mdx +++ b/openhands/usage/use-cases/dependency-upgrades.mdx @@ -6,19 +6,6 @@ automation: icon: arrow-up-right-dots card_description: >- Check for outdated packages weekly and report available updates. - prompt: | - Create an automation called "Dependency Checker" that runs every Monday at 8 AM. - - It should: - 1. Scan all package.json and requirements.txt files - 2. Check for outdated dependencies - 3. Create a report listing packages with available updates (grouped by major/minor/patch) - 4. Post the report to #engineering - alt_tab_title: Learn More - alt_tab_body: >- - See the [full use case guide](/openhands/usage/use-cases/dependency-upgrades) - for strategies on handling breaking changes, planning major upgrades, - and validating after updates. --- Keeping dependencies up to date is essential for security, performance, and access to new features. OpenHands can help you identify outdated dependencies, plan upgrades, handle breaking changes, and validate that your application still works after updates. @@ -297,9 +284,18 @@ addressing breaking changes in the correct order. ## Automate This - - Run this use case as a scheduled automation — copy a ready-to-use prompt from the Automation Examples page. - +You can schedule weekly dependency checks using [OpenHands Automations](/openhands/usage/automations/overview). +Copy this prompt into a new conversation to set one up: + +``` +Create an automation called "Dependency Checker" that runs every Monday at 8 AM. + +It should: +1. Scan all package.json and requirements.txt files +2. Check for outdated dependencies +3. Create a report listing packages with available updates (grouped by major/minor/patch) +4. Post the report to #engineering +``` ## Related Resources diff --git a/openhands/usage/use-cases/incident-triage.mdx b/openhands/usage/use-cases/incident-triage.mdx index 9091333ef..0e9b66cb4 100644 --- a/openhands/usage/use-cases/incident-triage.mdx +++ b/openhands/usage/use-cases/incident-triage.mdx @@ -5,19 +5,7 @@ automation: card_title: Incident Monitoring icon: triangle-exclamation card_description: >- - Monitor APIs, analyze errors, and alert your team. Pairs with the - [Datadog debugging workflow](https://github.com/OpenHands/software-agent-sdk/tree/main/examples/03_github_workflows/04_datadog_debugging). - prompt: | - Create an automation called "API Health Monitor" that runs every 30 minutes. - - It should check https://api.example.com/health and: - - If the response is not 200 OK, send an alert to #alerts with the status code and response body - - If healthy, just log success without alerting anyone - alt_tab_title: Plugin - alt_tab_body: >- - Use the [Datadog debugging workflow](https://github.com/OpenHands/software-agent-sdk/tree/main/examples/03_github_workflows/04_datadog_debugging) - for deeper error analysis with Datadog integration. See the - [full use case guide](/openhands/usage/use-cases/incident-triage). + Monitor API health, analyze errors, and alert your team automatically. --- - Run this use case as a scheduled automation — copy a ready-to-use prompt from the Automation Examples page. - +You can set up continuous health monitoring using [OpenHands Automations](/openhands/usage/automations/overview). +Copy this prompt into a new conversation to set one up: + +``` +Create an automation called "API Health Monitor" that runs every 30 minutes. + +It should check https://api.example.com/health and: +- If the response is not 200 OK, send an alert to #alerts with the status code and response body +- If healthy, just log success without alerting anyone +``` + +For deeper error analysis with Datadog integration, see the +[Datadog debugging workflow](https://github.com/OpenHands/software-agent-sdk/tree/main/examples/03_github_workflows/04_datadog_debugging). ## Related Resources diff --git a/openhands/usage/use-cases/vulnerability-remediation.mdx b/openhands/usage/use-cases/vulnerability-remediation.mdx index 84b1f2d2b..9cb1d52b2 100644 --- a/openhands/usage/use-cases/vulnerability-remediation.mdx +++ b/openhands/usage/use-cases/vulnerability-remediation.mdx @@ -5,22 +5,7 @@ automation: card_title: Vulnerability Scan icon: shield-halved card_description: >- - Scan dependencies for known CVEs and post a report. Pairs with the - [vulnerability-remediation plugin](https://github.com/OpenHands/extensions/tree/main/plugins/vulnerability-remediation). - prompt: | - Create an automation called "Security Scan" that runs daily at 3 AM. - - It should run a security audit: - 1. Check for known vulnerabilities in dependencies - 2. Scan for hardcoded secrets or API keys - 3. Look for common security misconfigurations - - Create a detailed report and alert #security if any high or critical issues are found. - alt_tab_title: Plugin - alt_tab_body: >- - Use the [vulnerability-remediation plugin](https://github.com/OpenHands/extensions/tree/main/plugins/vulnerability-remediation) - for a more thorough scan with automated fix PRs. See the - [full use case guide](/openhands/usage/use-cases/vulnerability-remediation). + Scan dependencies for known CVEs, find hardcoded secrets, and alert your team on a schedule. --- - Run this use case as a scheduled automation — copy a ready-to-use prompt from the Automation Examples page. - +You can run vulnerability scans on a schedule using [OpenHands Automations](/openhands/usage/automations/overview). +Copy this prompt into a new conversation to set one up: + +``` +Create an automation called "Security Scan" that runs daily at 3 AM. + +It should run a security audit: +1. Check for known vulnerabilities in dependencies +2. Scan for hardcoded secrets or API keys +3. Look for common security misconfigurations + +Create a detailed report and alert #security if any high or critical issues are found. +``` + +You can also use the [vulnerability-remediation plugin](https://github.com/OpenHands/extensions/tree/main/plugins/vulnerability-remediation) +for automated fix PRs alongside the scan. ## Related Resources From b4d92ee8932fec8aa0a8ee2ac36bba8cf4ebc068 Mon Sep 17 00:00:00 2001 From: openhands Date: Tue, 14 Apr 2026 15:16:13 +0000 Subject: [PATCH 6/8] feat: add doc page link to each automation prompt Each prompt now ends with 'Learn more at ' pointing back to the use-case documentation page, so users (and agents) always have context on where the prompt came from. Co-authored-by: openhands --- openhands/usage/use-cases/code-review.mdx | 2 ++ openhands/usage/use-cases/dependency-upgrades.mdx | 2 ++ openhands/usage/use-cases/incident-triage.mdx | 2 ++ openhands/usage/use-cases/vulnerability-remediation.mdx | 2 ++ 4 files changed, 8 insertions(+) diff --git a/openhands/usage/use-cases/code-review.mdx b/openhands/usage/use-cases/code-review.mdx index e5939a96c..581aa13dd 100644 --- a/openhands/usage/use-cases/code-review.mdx +++ b/openhands/usage/use-cases/code-review.mdx @@ -283,6 +283,8 @@ It should: 1. Find all open PRs that have no reviews yet 2. For each PR, review the diff for bugs, style issues, and security concerns 3. Post a summary of findings as a comment on each PR + +Learn more at https://docs.openhands.dev/openhands/usage/use-cases/code-review ``` For inline review comments on every push, use the diff --git a/openhands/usage/use-cases/dependency-upgrades.mdx b/openhands/usage/use-cases/dependency-upgrades.mdx index 335282a64..c104605f5 100644 --- a/openhands/usage/use-cases/dependency-upgrades.mdx +++ b/openhands/usage/use-cases/dependency-upgrades.mdx @@ -295,6 +295,8 @@ It should: 2. Check for outdated dependencies 3. Create a report listing packages with available updates (grouped by major/minor/patch) 4. Post the report to #engineering + +Learn more at https://docs.openhands.dev/openhands/usage/use-cases/dependency-upgrades ``` ## Related Resources diff --git a/openhands/usage/use-cases/incident-triage.mdx b/openhands/usage/use-cases/incident-triage.mdx index 0e9b66cb4..19ae1eece 100644 --- a/openhands/usage/use-cases/incident-triage.mdx +++ b/openhands/usage/use-cases/incident-triage.mdx @@ -273,6 +273,8 @@ Create an automation called "API Health Monitor" that runs every 30 minutes. It should check https://api.example.com/health and: - If the response is not 200 OK, send an alert to #alerts with the status code and response body - If healthy, just log success without alerting anyone + +Learn more at https://docs.openhands.dev/openhands/usage/use-cases/incident-triage ``` For deeper error analysis with Datadog integration, see the diff --git a/openhands/usage/use-cases/vulnerability-remediation.mdx b/openhands/usage/use-cases/vulnerability-remediation.mdx index 9cb1d52b2..82ee04591 100644 --- a/openhands/usage/use-cases/vulnerability-remediation.mdx +++ b/openhands/usage/use-cases/vulnerability-remediation.mdx @@ -295,6 +295,8 @@ It should run a security audit: 3. Look for common security misconfigurations Create a detailed report and alert #security if any high or critical issues are found. + +Learn more at https://docs.openhands.dev/openhands/usage/use-cases/vulnerability-remediation ``` You can also use the [vulnerability-remediation plugin](https://github.com/OpenHands/extensions/tree/main/plugins/vulnerability-remediation) From d616c679a19d50bfd72883c5778b7005011f6898 Mon Sep 17 00:00:00 2001 From: openhands Date: Tue, 14 Apr 2026 15:40:23 +0000 Subject: [PATCH 7/8] refactor: merge examples into overview, address review feedback MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Review fixes: - Remove card_title duplication — use page title instead - Rename card_description to summary (simpler frontmatter) - Add field validation with clear error messages for missing fields - Add marker validation (fail loudly on missing/misordered markers) - Add 13 tests covering parsing, generation, and error cases Page merge: - Merge automations/examples.mdx into automations/overview.mdx (single page with overview + use-case cards + general templates) - Delete the separate examples page - Update docs.json navigation - Fix all internal links across the site Co-authored-by: openhands --- .github/scripts/sync_use_case_automations.py | 129 +++++++++---- .../workflows/sync-use-case-automations.yml | 2 +- docs.json | 3 +- .../automations/creating-automations.mdx | 2 +- openhands/usage/automations/examples.mdx | 182 ------------------ .../automations/managing-automations.mdx | 2 +- openhands/usage/automations/overview.mdx | 167 +++++++++++++++- openhands/usage/use-cases/code-review.mdx | 3 +- .../usage/use-cases/dependency-upgrades.mdx | 3 +- openhands/usage/use-cases/incident-triage.mdx | 3 +- openhands/usage/use-cases/overview.mdx | 6 +- .../use-cases/vulnerability-remediation.mdx | 3 +- tests/test_sync_use_case_automations.py | 105 ++++++++++ 13 files changed, 376 insertions(+), 234 deletions(-) delete mode 100644 openhands/usage/automations/examples.mdx create mode 100644 tests/test_sync_use_case_automations.py diff --git a/.github/scripts/sync_use_case_automations.py b/.github/scripts/sync_use_case_automations.py index 21b4ea37e..8f19b12c4 100644 --- a/.github/scripts/sync_use_case_automations.py +++ b/.github/scripts/sync_use_case_automations.py @@ -1,22 +1,31 @@ #!/usr/bin/env python3 """ -Sync use-case automation cards to the automation examples page. +Sync use-case automation cards to the automations overview page. Each use-case page under ``openhands/usage/use-cases/`` is the **source of -truth**. If a page's YAML frontmatter contains an ``automation:`` block, the -script copies that content into the "Use Case Automations" section of -``openhands/usage/automations/examples.mdx``. +truth** for its automation content. If a page's YAML frontmatter contains +an ``automation:`` block, this script generates a card for it in the +automations overview page. -The generated section lives between marker comments in examples.mdx: +The generated card grid lives between marker comments: {/* BEGIN:use-case-automations */} … {/* END:use-case-automations */} +Each card links to the use-case page's ``#automate-this`` section where the +full prompt and instructions live. + +Required frontmatter fields inside ``automation:``: + - ``icon`` — Font Awesome icon name for the card + - ``summary`` — Short description shown on the card + +The page's ``title`` field is used as the card title (no duplication). + Usage: python .github/scripts/sync_use_case_automations.py # write mode python .github/scripts/sync_use_case_automations.py --check # CI check Exit codes: - 0 — examples page is in sync (or was updated in write mode) - 1 — examples page is out of sync (check mode) + 0 — target page is in sync (or was updated in write mode) + 1 — target page is out of sync (check mode) or validation error """ from __future__ import annotations @@ -29,10 +38,11 @@ import yaml REPO_ROOT = Path(__file__).resolve().parents[2] -EXAMPLES_PAGE = REPO_ROOT / "openhands" / "usage" / "automations" / "examples.mdx" +AUTOMATIONS_PAGE = REPO_ROOT / "openhands" / "usage" / "automations" / "overview.mdx" USE_CASES_DIR = REPO_ROOT / "openhands" / "usage" / "use-cases" FRONTMATTER_RE = re.compile(r"\A---\n(.*?)\n---", re.DOTALL) +REQUIRED_FIELDS = ("icon", "summary") # ── Frontmatter parsing ────────────────────────────────────────────── @@ -44,46 +54,65 @@ def parse_frontmatter(text: str) -> dict: return yaml.safe_load(m.group(1)) or {} -def collect_use_cases() -> list[tuple[str, dict]]: - """Return (slug, automation_dict) for every use-case with automation metadata.""" - results: list[tuple[str, dict]] = [] +def collect_use_cases() -> list[tuple[str, str, dict]]: + """Return (slug, page_title, automation_dict) for use-cases with automation metadata.""" + results: list[tuple[str, str, dict]] = [] + errors: list[str] = [] + for page in sorted(USE_CASES_DIR.glob("*.mdx")): if page.name == "overview.mdx": continue fm = parse_frontmatter(page.read_text()) - if "automation" in fm: - results.append((page.stem, fm["automation"])) + if "automation" not in fm: + continue + + auto = fm["automation"] + rel = page.relative_to(REPO_ROOT) + + for field in REQUIRED_FIELDS: + if field not in auto: + errors.append(f" {rel}: missing automation.{field}") + + if "title" not in fm: + errors.append(f" {rel}: missing top-level title") + + if not errors or all(f" {rel}" not in e for e in errors): + results.append((page.stem, fm["title"], auto)) + + if errors: + print("❌ Frontmatter validation errors:", file=sys.stderr) + for e in errors: + print(e, file=sys.stderr) + sys.exit(1) + return results # ── Generator ───────────────────────────────────────────────────────── -def generate_examples_section(use_cases: list[tuple[str, dict]]) -> str: - """Generate the ``use-case-automations`` block for *examples.mdx*. +def generate_card_section(use_cases: list[tuple[str, str, dict]]) -> str: + """Generate the ``use-case-automations`` card grid. - Each card links to the "Automate This" section of the corresponding - use-case page, where the full prompt and instructions live. + Each card links to the use-case page's #automate-this section. """ parts: list[str] = [] parts.append( - "## Use Case Automations\n" - "\n" "Each use case has a ready-to-use automation prompt. " "Click a card to see the full instructions.\n" "\n" "" ) - for slug, auto in use_cases: + for slug, title, auto in use_cases: parts.append( f' \n' - f' {auto["card_description"]}\n' + f' {auto["summary"]}\n' f' ' ) @@ -94,7 +123,10 @@ def generate_examples_section(use_cases: list[tuple[str, dict]]) -> str: # ── Marker replacement ─────────────────────────────────────────────── -def replace_marker_section(content: str, marker: str, new_body: str) -> str: + +def replace_marker_section( + content: str, marker: str, new_body: str, filepath: Path +) -> str: """Replace everything between BEGIN: and END:.""" begin_pat = re.compile( rf"\{{/\*\s*BEGIN:{re.escape(marker)}\s*(?:—[^*]*)?\*/\}}" @@ -106,8 +138,34 @@ def replace_marker_section(content: str, marker: str, new_body: str) -> str: begin_m = begin_pat.search(content) end_m = end_pat.search(content) - if not begin_m or not end_m: - return content + if not begin_m and not end_m: + print( + f"❌ {filepath.relative_to(REPO_ROOT)}: " + f"missing both BEGIN:{marker} and END:{marker} markers", + file=sys.stderr, + ) + sys.exit(1) + if not begin_m: + print( + f"❌ {filepath.relative_to(REPO_ROOT)}: " + f"missing BEGIN:{marker} marker", + file=sys.stderr, + ) + sys.exit(1) + if not end_m: + print( + f"❌ {filepath.relative_to(REPO_ROOT)}: " + f"missing END:{marker} marker", + file=sys.stderr, + ) + sys.exit(1) + if begin_m.start() >= end_m.start(): + print( + f"❌ {filepath.relative_to(REPO_ROOT)}: " + f"BEGIN:{marker} must come before END:{marker}", + file=sys.stderr, + ) + sys.exit(1) return ( content[: begin_m.start()] @@ -122,14 +180,15 @@ def replace_marker_section(content: str, marker: str, new_body: str) -> str: # ── Main ────────────────────────────────────────────────────────────── + def main() -> int: parser = argparse.ArgumentParser( - description="Sync use-case automation cards to the examples page." + description="Sync use-case automation cards to the automations page." ) parser.add_argument( "--check", action="store_true", - help="Check mode: exit 1 if files are out of sync (for CI).", + help="Check mode: exit 1 if the page is out of sync (for CI).", ) args = parser.parse_args() @@ -138,17 +197,19 @@ def main() -> int: print("No use-case pages with automation frontmatter found.") return 0 - original = EXAMPLES_PAGE.read_text() - generated = generate_examples_section(use_cases) - updated = replace_marker_section(original, "use-case-automations", generated) + original = AUTOMATIONS_PAGE.read_text() + generated = generate_card_section(use_cases) + updated = replace_marker_section( + original, "use-case-automations", generated, AUTOMATIONS_PAGE + ) if updated == original: - print("✅ Automation examples page is in sync.") + print("✅ Automations page is in sync.") return 0 if args.check: print( - "❌ openhands/usage/automations/examples.mdx is out of sync " + f"❌ {AUTOMATIONS_PAGE.relative_to(REPO_ROOT)} is out of sync " "with use-case frontmatter.\n" "\n" "Run: python .github/scripts/sync_use_case_automations.py\n" @@ -156,8 +217,8 @@ def main() -> int: ) return 1 - EXAMPLES_PAGE.write_text(updated) - print(f"✅ Updated {EXAMPLES_PAGE.relative_to(REPO_ROOT)}") + AUTOMATIONS_PAGE.write_text(updated) + print(f"✅ Updated {AUTOMATIONS_PAGE.relative_to(REPO_ROOT)}") return 0 diff --git a/.github/workflows/sync-use-case-automations.yml b/.github/workflows/sync-use-case-automations.yml index 1e71fcd8f..3cb603ff3 100644 --- a/.github/workflows/sync-use-case-automations.yml +++ b/.github/workflows/sync-use-case-automations.yml @@ -5,7 +5,7 @@ on: branches: - '**' paths: - - 'openhands/usage/automations/examples.mdx' + - 'openhands/usage/automations/overview.mdx' - 'openhands/usage/use-cases/**' - '.github/scripts/sync_use_case_automations.py' - '.github/workflows/sync-use-case-automations.yml' diff --git a/docs.json b/docs.json index 0dc442dda..de1396c7e 100644 --- a/docs.json +++ b/docs.json @@ -416,8 +416,7 @@ "pages": [ "openhands/usage/automations/overview", "openhands/usage/automations/creating-automations", - "openhands/usage/automations/managing-automations", - "openhands/usage/automations/examples" + "openhands/usage/automations/managing-automations" ] } ] diff --git a/openhands/usage/automations/creating-automations.mdx b/openhands/usage/automations/creating-automations.mdx index 99a4b58ca..14dd9c4ee 100644 --- a/openhands/usage/automations/creating-automations.mdx +++ b/openhands/usage/automations/creating-automations.mdx @@ -141,5 +141,5 @@ Once your automation is created: ## Next Steps -- [View example automations](/openhands/usage/automations/examples) +- [Automations overview & examples](/openhands/usage/automations/overview) - [Manage your automations](/openhands/usage/automations/managing-automations) diff --git a/openhands/usage/automations/examples.mdx b/openhands/usage/automations/examples.mdx deleted file mode 100644 index d4350f1a5..000000000 --- a/openhands/usage/automations/examples.mdx +++ /dev/null @@ -1,182 +0,0 @@ ---- -title: Automation Examples -description: Ready-to-use automation templates organized by use case. Copy a prompt, paste it into OpenHands, and you're running. ---- - - -**Beta Feature**: Automations is currently in beta and available for **OpenHands Cloud** and **OpenHands Enterprise** users only. - - -Browse automation templates below. Each card includes a ready-to-use prompt—just copy it into an OpenHands conversation and the agent will set everything up for you. - - -These examples reference services like Slack and GitHub. Git providers you logged in with are automatically available, but other services like Slack require [MCP configuration](/openhands/usage/settings/mcp-settings). - - -{/* BEGIN:use-case-automations — auto-generated from use-case frontmatter */} - -## Use Case Automations - -Each use case has a ready-to-use automation prompt. Click a card to see the full instructions. - - - - Review open PRs daily for bugs, style issues, and security concerns. - - - Check for outdated packages weekly and report available updates. - - - Monitor API health, analyze errors, and alert your team automatically. - - - Scan dependencies for known CVEs, find hardcoded secrets, and alert your team on a schedule. - - - -{/* END:use-case-automations */} - ---- - -## General Automations - -Ready-to-use templates for common operational tasks. - - - - Summarize PRs opened, merged, and reviewed daily. - - - Generate weekly GitHub activity and issue reports. - - - Check SSL expiry dates and alert before they lapse. - - - Remove stale temporary files and report what was cleaned. - - - Verify database backups exist and are recent. - - - Pull analytics data periodically and flag big changes. - - - -### Daily GitHub Summary - -``` -Create an automation called "Daily GitHub Summary" that runs every weekday at 9 AM Eastern. - -It should: -1. Summarize PRs opened, merged, and reviewed in the last 24 hours -2. List any PRs that have been open for more than 3 days -3. Format as a clean markdown summary -4. Post to the #engineering Slack channel -``` - -### Weekly Metrics Report - -``` -Create an automation called "Weekly Metrics" that runs every Monday at 9 AM. - -It should generate a weekly report covering: -- GitHub activity (commits, PRs merged, issues closed) -- Open issues grouped by priority -- PRs awaiting review for more than 3 days - -Save the report to weekly-reports/ with the current date in the filename. -``` - -### SSL Certificate Monitor - -``` -Create an automation called "SSL Monitor" that runs daily at 8 AM. - -It should check SSL certificate expiry for these domains: -- api.example.com -- app.example.com -- www.example.com - -If any certificate expires within 30 days, alert #devops with the domain and days remaining. -``` - -### Weekly Cleanup - -``` -Create an automation called "Weekly Cleanup" that runs every Sunday at 2 AM UTC. - -It should: -1. Find and delete temporary files older than 7 days -2. Create a summary of what was removed (file paths and sizes) -3. Post the cleanup summary to #ops -``` - -### Backup Verification - -``` -Create an automation called "Backup Check" that runs daily at 6 AM. - -It should verify that database backups exist and were created within the last 24 hours. -List the most recent backup for each database with its timestamp and size. -If any backup is missing or stale, send an urgent alert to #alerts. -``` - -### Analytics Data Sync - -``` -Create an automation called "Analytics Sync" that runs every 6 hours. - -It should: -1. Pull the latest data from our analytics API -2. Update metrics.json with the new data -3. Calculate week-over-week changes for key metrics -4. If any metric changed by more than 20%, flag it in a summary message -``` - ---- - -## Tips for Writing Good Prompts - - - - Tell the automation exactly what to do: - - "Check X and if Y, then Z" - - "Generate a report and save it to..." - - "Fetch data, compare with expected values, and report differences" - - - Specify what should happen when things go wrong: - - "If the response is not 200..." - - "If any backup is missing..." - - "If the check fails, alert the team" - - - Be explicit about outputs: - - "Post to the #channel Slack channel" - - "Save to reports/ with the current date" - - "Create a GitHub issue with the findings" - - - -## Next Steps - -- [Creating Automations](/openhands/usage/automations/creating-automations) — More details on writing prompts -- [Managing Automations](/openhands/usage/automations/managing-automations) — Update, disable, or delete automations -- [Use Cases Overview](/openhands/usage/use-cases/overview) — Explore the full use case guides behind these automations diff --git a/openhands/usage/automations/managing-automations.mdx b/openhands/usage/automations/managing-automations.mdx index 86575456a..88bb02f00 100644 --- a/openhands/usage/automations/managing-automations.mdx +++ b/openhands/usage/automations/managing-automations.mdx @@ -98,5 +98,5 @@ Deleting an automation is permanent. Consider disabling it instead if you might ## Next Steps -- [View example automations](/openhands/usage/automations/examples) +- [Automations overview & examples](/openhands/usage/automations/overview) - [Create new automations](/openhands/usage/automations/creating-automations) diff --git a/openhands/usage/automations/overview.mdx b/openhands/usage/automations/overview.mdx index 475f604d6..85c8003c0 100644 --- a/openhands/usage/automations/overview.mdx +++ b/openhands/usage/automations/overview.mdx @@ -102,7 +102,170 @@ You can also list existing automations, enable/disable them, or trigger manual r - **Configured LLM** in your [settings](https://app.all-hands.dev/settings) - **Stored secrets** (optional) for any additional API keys your automations need (e.g., Slack tokens) +--- + +## Use Case Automations + +{/* BEGIN:use-case-automations — auto-generated from use-case frontmatter */} + +Each use case has a ready-to-use automation prompt. Click a card to see the full instructions. + + + + Review open PRs daily for bugs, style issues, and security concerns. + + + Check for outdated packages weekly and report available updates. + + + Monitor API health, analyze errors, and alert your team automatically. + + + Scan dependencies for known CVEs, find hardcoded secrets, and alert your team on a schedule. + + + +{/* END:use-case-automations */} + +## General Automations + +Ready-to-use templates for common operational tasks. + + + + Summarize PRs opened, merged, and reviewed daily. + + + Generate weekly GitHub activity and issue reports. + + + Check SSL expiry dates and alert before they lapse. + + + Remove stale temporary files and report what was cleaned. + + + Verify database backups exist and are recent. + + + Pull analytics data periodically and flag big changes. + + + +### Daily GitHub Summary + +``` +Create an automation called "Daily GitHub Summary" that runs every weekday at 9 AM Eastern. + +It should: +1. Summarize PRs opened, merged, and reviewed in the last 24 hours +2. List any PRs that have been open for more than 3 days +3. Format as a clean markdown summary +4. Post to the #engineering Slack channel +``` + +### Weekly Metrics Report + +``` +Create an automation called "Weekly Metrics" that runs every Monday at 9 AM. + +It should generate a weekly report covering: +- GitHub activity (commits, PRs merged, issues closed) +- Open issues grouped by priority +- PRs awaiting review for more than 3 days + +Save the report to weekly-reports/ with the current date in the filename. +``` + +### SSL Certificate Monitor + +``` +Create an automation called "SSL Monitor" that runs daily at 8 AM. + +It should check SSL certificate expiry for these domains: +- api.example.com +- app.example.com +- www.example.com + +If any certificate expires within 30 days, alert #devops with the domain and days remaining. +``` + +### Weekly Cleanup + +``` +Create an automation called "Weekly Cleanup" that runs every Sunday at 2 AM UTC. + +It should: +1. Find and delete temporary files older than 7 days +2. Create a summary of what was removed (file paths and sizes) +3. Post the cleanup summary to #ops +``` + +### Backup Verification + +``` +Create an automation called "Backup Check" that runs daily at 6 AM. + +It should verify that database backups exist and were created within the last 24 hours. +List the most recent backup for each database with its timestamp and size. +If any backup is missing or stale, send an urgent alert to #alerts. +``` + +### Analytics Data Sync + +``` +Create an automation called "Analytics Sync" that runs every 6 hours. + +It should: +1. Pull the latest data from our analytics API +2. Update metrics.json with the new data +3. Calculate week-over-week changes for key metrics +4. If any metric changed by more than 20%, flag it in a summary message +``` + +--- + +## Tips for Writing Good Prompts + + + + Tell the automation exactly what to do: + - "Check X and if Y, then Z" + - "Generate a report and save it to..." + - "Fetch data, compare with expected values, and report differences" + + + Specify what should happen when things go wrong: + - "If the response is not 200..." + - "If any backup is missing..." + - "If the check fails, alert the team" + + + Be explicit about outputs: + - "Post to the #channel Slack channel" + - "Save to reports/ with the current date" + - "Create a GitHub issue with the findings" + + + ## Next Steps -- [Creating Automations](/openhands/usage/automations/creating-automations) — Detailed guide with prompt tips -- [Examples](/openhands/usage/automations/examples) — Common automation patterns +- [Creating Automations](/openhands/usage/automations/creating-automations) — More details on writing prompts +- [Managing Automations](/openhands/usage/automations/managing-automations) — Update, disable, or delete automations +- [Use Cases Overview](/openhands/usage/use-cases/overview) — Explore the full use case guides behind these automations diff --git a/openhands/usage/use-cases/code-review.mdx b/openhands/usage/use-cases/code-review.mdx index 581aa13dd..22e0d1efd 100644 --- a/openhands/usage/use-cases/code-review.mdx +++ b/openhands/usage/use-cases/code-review.mdx @@ -2,9 +2,8 @@ title: Automated Code Review description: Set up automated PR reviews using OpenHands and the Software Agent SDK automation: - card_title: Automated Code Review icon: code-pull-request - card_description: >- + summary: >- Review open PRs daily for bugs, style issues, and security concerns. --- diff --git a/openhands/usage/use-cases/dependency-upgrades.mdx b/openhands/usage/use-cases/dependency-upgrades.mdx index c104605f5..53b3867f0 100644 --- a/openhands/usage/use-cases/dependency-upgrades.mdx +++ b/openhands/usage/use-cases/dependency-upgrades.mdx @@ -2,9 +2,8 @@ title: Dependency Upgrades description: Automating dependency updates and upgrades with OpenHands automation: - card_title: Dependency Upgrades icon: arrow-up-right-dots - card_description: >- + summary: >- Check for outdated packages weekly and report available updates. --- diff --git a/openhands/usage/use-cases/incident-triage.mdx b/openhands/usage/use-cases/incident-triage.mdx index 19ae1eece..f5156b919 100644 --- a/openhands/usage/use-cases/incident-triage.mdx +++ b/openhands/usage/use-cases/incident-triage.mdx @@ -2,9 +2,8 @@ title: Incident Triage description: Using OpenHands to investigate and resolve production incidents automation: - card_title: Incident Monitoring icon: triangle-exclamation - card_description: >- + summary: >- Monitor API health, analyze errors, and alert your team automatically. --- diff --git a/openhands/usage/use-cases/overview.mdx b/openhands/usage/use-cases/overview.mdx index 76bc55d0f..8229b463f 100644 --- a/openhands/usage/use-cases/overview.mdx +++ b/openhands/usage/use-cases/overview.mdx @@ -5,7 +5,7 @@ description: Explore how OpenHands can help with common software development cha OpenHands supports a wide variety of software development tasks. Here are some of the key use cases where OpenHands can help accelerate your work. -Each use case can be implemented in different ways—as a one-off conversation, a scheduled [automation](/openhands/usage/automations/examples), a [plugin](https://github.com/OpenHands/extensions), or through the [SDK](/sdk/index). Pick the approach that fits your workflow. +Each use case can be implemented in different ways—as a one-off conversation, a scheduled [automation](/openhands/usage/automations/overview), a [plugin](https://github.com/OpenHands/extensions), or through the [SDK](/sdk/index). Pick the approach that fits your workflow. - + Ready-to-use prompts for vulnerability scans, code reviews, monitoring, and more. diff --git a/openhands/usage/use-cases/vulnerability-remediation.mdx b/openhands/usage/use-cases/vulnerability-remediation.mdx index 82ee04591..d56322360 100644 --- a/openhands/usage/use-cases/vulnerability-remediation.mdx +++ b/openhands/usage/use-cases/vulnerability-remediation.mdx @@ -2,9 +2,8 @@ title: Vulnerability Remediation description: Using OpenHands to identify and fix security vulnerabilities in your codebase automation: - card_title: Vulnerability Scan icon: shield-halved - card_description: >- + summary: >- Scan dependencies for known CVEs, find hardcoded secrets, and alert your team on a schedule. --- diff --git a/tests/test_sync_use_case_automations.py b/tests/test_sync_use_case_automations.py new file mode 100644 index 000000000..7f208a584 --- /dev/null +++ b/tests/test_sync_use_case_automations.py @@ -0,0 +1,105 @@ +"""Tests for sync_use_case_automations.py.""" + +import sys +from pathlib import Path + +import pytest + +sys.path.insert(0, str(Path(__file__).parent.parent / ".github" / "scripts")) + +from sync_use_case_automations import ( + REPO_ROOT, + generate_card_section, + parse_frontmatter, + replace_marker_section, +) + + +class TestParseFrontmatter: + def test_valid(self): + text = "---\ntitle: Hello\nautomation:\n icon: star\n summary: A test\n---\nbody" + fm = parse_frontmatter(text) + assert fm["title"] == "Hello" + assert fm["automation"]["icon"] == "star" + assert fm["automation"]["summary"] == "A test" + + def test_no_frontmatter(self): + assert parse_frontmatter("just body text") == {} + + def test_empty_frontmatter(self): + assert parse_frontmatter("---\n---\nbody") == {} + + +class TestGenerateCardSection: + def test_single_card(self): + use_cases = [("my-page", "My Page Title", {"icon": "star", "summary": "Short desc."})] + output = generate_card_section(use_cases) + assert 'title="My Page Title"' in output + assert 'icon="star"' in output + assert 'href="/openhands/usage/use-cases/my-page#automate-this"' in output + assert "Short desc." in output + assert "" in output + + def test_multiple_cards_preserve_order(self): + cases = [ + ("aaa", "Alpha", {"icon": "a", "summary": "First"}), + ("bbb", "Beta", {"icon": "b", "summary": "Second"}), + ] + output = generate_card_section(cases) + assert output.index("Alpha") < output.index("Beta") + + def test_empty(self): + output = generate_card_section([]) + assert "" in output + assert 'href=' not in output + + +class TestReplaceMarkerSection: + TEMPLATE = ( + "before\n" + "{/* BEGIN:test-marker */}\nold content\n{/* END:test-marker */}\n" + "after" + ) + DUMMY_PATH = REPO_ROOT / "fake-file.mdx" + + def test_replaces_content(self): + result = replace_marker_section(self.TEMPLATE, "test-marker", "new stuff", self.DUMMY_PATH) + assert "new stuff" in result + assert "old content" not in result + assert "before" in result + assert "after" in result + + def test_preserves_markers(self): + result = replace_marker_section(self.TEMPLATE, "test-marker", "X", self.DUMMY_PATH) + assert "BEGIN:test-marker" in result + assert "END:test-marker" in result + + def test_missing_begin_marker(self): + content = "no markers here\n{/* END:test-marker */}" + with pytest.raises(SystemExit): + replace_marker_section(content, "test-marker", "X", self.DUMMY_PATH) + + def test_missing_end_marker(self): + content = "{/* BEGIN:test-marker */}\nstuff" + with pytest.raises(SystemExit): + replace_marker_section(content, "test-marker", "X", self.DUMMY_PATH) + + def test_missing_both_markers(self): + with pytest.raises(SystemExit): + replace_marker_section("nothing here", "test-marker", "X", self.DUMMY_PATH) + + def test_begin_after_end(self): + content = "{/* END:test-marker */}\n{/* BEGIN:test-marker */}" + with pytest.raises(SystemExit): + replace_marker_section(content, "test-marker", "X", self.DUMMY_PATH) + + def test_marker_with_comment(self): + content = ( + "{/* BEGIN:test-marker — auto-generated */}\nold\n" + "{/* END:test-marker */}" + ) + result = replace_marker_section(content, "test-marker", "new", self.DUMMY_PATH) + assert "new" in result + assert "old" not in result From 2719ca2496e3627c32e21b832d03b9093b1a5079 Mon Sep 17 00:00:00 2001 From: openhands Date: Tue, 14 Apr 2026 15:47:31 +0000 Subject: [PATCH 8/8] fix: simplify error handling, add redirect for deleted examples page - Replace confusing 'all(f" {rel}" not in e ...)' with simple 'file_has_errors' boolean flag per reviewer suggestion - Add redirect from /automations/examples to /automations/overview so external links don't 404 Co-authored-by: openhands --- .agents/skills/verify/SKILL.md | 206 +++++++++++++++++++ .github/scripts/sync_use_case_automations.py | 5 +- docs.json | 4 + 3 files changed, 214 insertions(+), 1 deletion(-) create mode 100644 .agents/skills/verify/SKILL.md diff --git a/.agents/skills/verify/SKILL.md b/.agents/skills/verify/SKILL.md new file mode 100644 index 000000000..c0254e2cd --- /dev/null +++ b/.agents/skills/verify/SKILL.md @@ -0,0 +1,206 @@ +--- +name: verify +description: >- + Orchestrate repo-level verification of a PR by pushing changes, then polling + CI checks, PR review, and QA workflows until all pass — or until issues are + found that need fixing. The agent reads feedback, fixes code, pushes again, + and repeats. Uses only standard `gh` CLI commands that work on any GitHub repo. +triggers: +- /verify +--- + +# /verify — Repo-Level Verification via Polling + +Orchestrate the push → poll → fix → push loop for a pull request. +You poll the repo's verifiers with `gh` CLI, read feedback, fix issues, and iterate. +No scripts — you are the orchestration loop. + +Requires: `gh` CLI authenticated with repo access, a PR branch. + +## Discover what the repo has + +Not every repo has all three verification layers. Before entering the loop, +check which ones exist. Only poll layers that are actually set up. + +```bash +gh workflow list --json name --jq '.[].name' +``` + +- **CI checks** — almost every repo has these. If `gh pr checks` returns results, CI is present. +- **PR review bot** — look for a workflow named like "PR Review" or "pr-review" in the output above, or check for `.github/workflows/pr-review*.yml` in the repo. If it's not there, the repo doesn't have automated PR review. Skip step 3 entirely. +- **QA bot** — look for a workflow named like "QA" or "qa-changes". If it's not there, the repo doesn't have automated QA. Skip step 4 entirely. + +A repo might have only CI. Or CI + review. Or all three. Your "all passed" +condition is: every *present* layer is green. Don't block waiting for layers +that don't exist. + +## The loop + +1. Push and ensure PR exists. +2. Poll each present verification layer. +3. Decide: all passed? fix needed? wait? +4. If fix needed — fix, commit, push, re-request review from bots, go to 2. +5. If waiting — sleep 30-60s, go to 2. +6. If all present layers passed on the *current* SHA — done. + +IMPORTANT: pushing a fix is NOT the end. After every fix+push you MUST +re-request review from the review bot (if present) and go back to step 2. +The loop only ends when the verifiers pass on your latest SHA. Addressing +feedback and pushing a commit is just one iteration — the bot needs to +review the new code too. + +## Step 1 — Push and ensure PR exists + +```bash +git push origin HEAD +gh pr create --fill 2>/dev/null || true +gh pr view --json number,url,headRefOid --jq '"\(.number) \(.url) \(.headRefOid)"' +``` + +## Step 2 — Poll CI checks + +```bash +gh pr checks --json name,state,bucket --jq ' + { passed: [.[] | select(.bucket=="pass")] | length, + failed: [.[] | select(.bucket=="fail")] | length, + pending: [.[] | select(.bucket=="pending")] | length }' +``` + +- Zero failed, zero pending → CI green. +- Any pending → wait and re-poll. +- Any failed → diagnose (see "CI failure classification" below). + +To inspect a failure: + +```bash +SHA=$(gh pr view --json headRefOid --jq .headRefOid) +gh run list --commit "$SHA" --status failure --json databaseId,name,conclusion \ + --jq '.[] | "\(.databaseId)\t\(.name)\t\(.conclusion)"' +gh run view --log-failed +``` + +## Step 3 — Poll PR review (if present) + +Skip this step if the repo has no review bot. + +```bash +gh pr view --json reviews --jq ' + [.reviews[] | select( + .authorAssociation == "OWNER" or + .authorAssociation == "MEMBER" or + .authorAssociation == "COLLABORATOR" or + (.author.login | test("openhands|all-hands-bot"; "i")) + )] | last | { state: .state, reviewer: .author.login, body: .body[0:300] }' +``` + +- `APPROVED` → review passed. +- `CHANGES_REQUESTED` → read the body and inline comments, fix code. +- `COMMENTED` → may have actionable suggestions; read and decide. +- No matching review yet → bot may still be running; wait and re-poll. + +Inline review comments (when changes requested): + +```bash +gh api "repos/{owner}/{repo}/pulls/{number}/comments" \ + --jq '.[] | select(.user.login | test("openhands|all-hands-bot"; "i")) + | { path: .path, line: .line, body: .body[0:200] }' +``` + +## Step 4 — Poll QA report (if present) + +Skip this step if the repo has no QA bot. + +QA reports are PR issue comments with a status line like `Status: PASS`. + +```bash +gh api "repos/{owner}/{repo}/issues/{number}/comments" --paginate \ + --jq '[.[] | select( + (.user.login | test("openhands|all-hands-bot"; "i")) and + (.body | test("Status:\\s*(PASS|FAIL|PARTIAL)"; "i")) + )] | last | { author: .user.login, body: .body[0:500], url: .html_url }' +``` + +- `PASS` → QA passed. +- `FAIL` → read details, fix code. +- `PARTIAL` → some passed, some failed; read details. +- No QA comment yet → bot may still be running; wait and re-poll. + +## Step 5 — Decide and act + +For each present layer, check its status. If a layer is not present in the +repo, treat it as passing. + +- All present layers green on current SHA → done. +- CI failed → fix code, or rerun if flaky (see below). +- Review requested changes → read comments, fix, push. +- QA failed/partial → read report, fix, push. +- Anything still pending → sleep 30-60s, re-poll. +- PR closed/merged → stop. + +After fixing, commit, push, AND re-request review: + +```bash +git add -A +git commit -m "fix: address " +git push origin HEAD + +# Re-request review from the bot so it reviews the new SHA: +gh pr comment --body "Addressed feedback in $(git rev-parse --short HEAD). Ready for another look." +gh api -X POST "repos/{owner}/{repo}/pulls/{number}/requested_reviewers" \ + -f 'reviewers[]=all-hands-bot' +``` + +Then go back to step 2. You are not done until the bot reviews the new +SHA and all present layers pass. + +## CI failure classification + +Branch-related (fix the code): +- Compile/lint/typecheck failures in files you touched +- Deterministic test failures in changed areas +- Snapshot or static-analysis violations from your changes + +Flaky / unrelated (rerun the jobs): +- Network/DNS/registry timeouts +- Runner provisioning or startup failures +- GitHub Actions infrastructure errors +- Non-deterministic failures in code you didn't touch + +Rerun: `gh run rerun --failed` + +Retry budget: at most 3 reruns per SHA. After that, treat as real. + +## Stop conditions + +Stop ONLY when: +- All present verification layers passed on the current SHA. +- PR closed or merged (`gh pr view --json state --jq .state`). +- Retry budget exhausted — CI still failing after 3 reruns of the same SHA. +- Blocked on something requiring user input. + +NOT a stop condition: +- You pushed a fix commit. That's just one iteration — re-request review and keep going. +- You replied to review comments. The bot still needs to review the new code. +- CI is green but review bot hasn't re-reviewed your fix yet. Wait for it. + +Keep going when: +- Checks still pending. +- Bots haven't posted yet (few minutes after push). +- Just pushed a fix and CI hasn't started. + +## Polling cadence + +- CI pending/failing: every 30-60s. +- CI green: back off (60s, 2m, 4m), reset on any state change. +- Just pushed a fix: re-poll immediately. + +## vs babysit-pr + +`/verify` is an active orchestrator — you write code, push, poll, fix, repeat. +`/babysit-pr` is a passive monitor — watches someone else's PR via a Python script. +Use `/verify` when you're the coding agent. Use `/babysit-pr` when you just need to watch. + +## References + +- Verification signal details: `references/workflow-signals.md` +- CI failure heuristics: same as `babysit-pr/references/heuristics.md` diff --git a/.github/scripts/sync_use_case_automations.py b/.github/scripts/sync_use_case_automations.py index 8f19b12c4..df40cb2b4 100644 --- a/.github/scripts/sync_use_case_automations.py +++ b/.github/scripts/sync_use_case_automations.py @@ -68,15 +68,18 @@ def collect_use_cases() -> list[tuple[str, str, dict]]: auto = fm["automation"] rel = page.relative_to(REPO_ROOT) + file_has_errors = False for field in REQUIRED_FIELDS: if field not in auto: errors.append(f" {rel}: missing automation.{field}") + file_has_errors = True if "title" not in fm: errors.append(f" {rel}: missing top-level title") + file_has_errors = True - if not errors or all(f" {rel}" not in e for e in errors): + if not file_has_errors: results.append((page.stem, fm["title"], auto)) if errors: diff --git a/docs.json b/docs.json index de1396c7e..62905d8df 100644 --- a/docs.json +++ b/docs.json @@ -702,6 +702,10 @@ { "source": "/openhands/usage/runtimes/daytona", "destination": "/openhands/usage/v0/runtimes/V0_daytona" + }, + { + "source": "/openhands/usage/automations/examples", + "destination": "/openhands/usage/automations/overview" } ] }