@openhands/extensions 0.3.0 → 0.4.1

package/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.3.0"
+  ".": "0.4.1"
 }

package/README.md

@@ -60,7 +60,7 @@ See [`integrations/README.md`](integrations/README.md), [`automations/README.md`
 ## Extensions Catalog
 
 <!-- BEGIN AUTO-GENERATED CATALOG -->
-This repository contains **2 marketplace(s)** with **56 extensions** (46 skills, 10 plugins).
+This repository contains **2 marketplace(s)** with **57 extensions** (47 skills, 10 plugins).
 
 ### large-codebase
 
@@ -79,7 +79,7 @@ OpenHands skills for interacting, improving, and refactoring large codebases
 
 Official skills and plugins for OpenHands — the open-source AI software engineer.
 
-**52 extensions** (44 skills, 8 plugins)
+**53 extensions** (45 skills, 8 plugins)
 
 | Name | Type | Description | Commands |
 |------|------|-------------|----------|
@@ -100,6 +100,7 @@ Official skills and plugins for OpenHands — the open-source AI software engine
 | flarglebargle | skill | A test skill that responds to the magic word 'flarglebargle' with a compliment. Use for testing skill activation and ... | — |
 | frontend-design | skill | Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks ... | — |
 | github | skill | Interact with GitHub repositories, pull requests, issues, and workflows using the GITHUB_TOKEN environment variable a... | — |
+| github-actions | skill | Create, debug, and test GitHub Actions workflows and custom actions. Use when building CI/CD pipelines, automating wo... | — |
 | github-pr-review | skill | Post structured PR reviews to GitHub with inline comments/suggestions in a single API call. | `/github-pr-review` |
 | github-pr-reviewer | skill | Create an automation that reviews GitHub pull requests when they are opened or updated. Inspects the diff, changed fi... | `/pr-reviewer:setup` |
 | github-repo-monitor | skill | Create a cron automation that polls a GitHub repository for issue and PR comments containing a configurable trigger p... | `/github-monitor:poll` |

package/automations/catalog/github-pr-reviewer.json

@@ -1,6 +1,6 @@
 {
   "id": "github-pr-reviewer",
-  "name": "GitHub PR review copilot",
+  "name": "GitHub Code Review Agent",
   "category": "Code review",
   "description": "Watch pull requests, inspect the diff, and leave a concise review with risks and suggested follow-ups.",
   "requiredIntegrationIds": [

package/automations/catalog/github-repo-monitor.json

@@ -7,5 +7,5 @@
   "popularityRank": 98,
   "estimatedSetupMinutes": 5,
   "prompt": "/github-monitor:poll",
-  "exampleImplementation": "Trigger: cron, every minute (configurable)\nRequired secret: GITHUB_TOKEN\n\n1. Poll GitHub for new issue and PR comments since the last run.\n2. Match comments containing the trigger phrase (case-insensitive, default: @OpenHands).\n3. Post an acknowledgment comment with a link to the new OpenHands conversation.\n4. Forward follow-up replies in the same thread to the running conversation.\n5. Post the agent's final response back to GitHub when the conversation completes."
+  "exampleImplementation": "Trigger: cron, every minute (configurable)\nRequired secret: GITHUB_PERSONAL_ACCESS_TOKEN\n\n1. Poll GitHub for new issue and PR comments since the last run.\n2. Match comments containing the trigger phrase (case-insensitive, default: @OpenHands).\n3. Post an acknowledgment comment with a link to the new OpenHands conversation.\n4. Forward follow-up replies in the same thread to the running conversation.\n5. Post the agent's final response back to GitHub when the conversation completes."
 }

package/marketplaces/openhands-extensions.json

@@ -238,6 +238,19 @@
         "workflows"
       ]
     },
+    {
+      "name": "github-actions",
+      "source": "./skills/github-actions",
+      "description": "Create, debug, and test GitHub Actions workflows and custom actions. Use when building CI/CD pipelines, automating workflows, or troubleshooting GitHub Actions.",
+      "category": "integration",
+      "keywords": [
+        "github-actions",
+        "workflows",
+        "ci-cd",
+        "automation",
+        "actions"
+      ]
+    },
     {
       "name": "github-pr-review",
       "source": "./skills/github-pr-review",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openhands/extensions",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "description": "Public OpenHands extension catalogs for skills, plugins, integrations, and automation templates.",
   "license": "MIT",
   "type": "module",

package/plugins/issue-duplicate-checker/action.yml

@@ -258,7 +258,7 @@ runs:
           if: inputs.mode == 'issue-check' && steps.parsed_result.outputs.should_comment == 'true'
           uses: actions/github-script@v9
           env:
-              ACTION_SCRIPT: ${{ github.action_path }}/scripts/post_duplicate_notice.js
+              ACTION_SCRIPT: ${{ github.action_path }}/scripts/post_duplicate_notice.cjs
               ISSUE_NUMBER: ${{ inputs.issue-number }}
               SUMMARY: ${{ steps.parsed_result.outputs.summary }}
               CANDIDATE_ISSUES_JSON: ${{ steps.parsed_result.outputs.candidate_issues_json }}
@@ -341,7 +341,7 @@ runs:
           if: inputs.mode == 'remove-label'
           uses: actions/github-script@v9
           env:
-              ACTION_SCRIPT: ${{ github.action_path }}/scripts/remove_duplicate_candidate_label.js
+              ACTION_SCRIPT: ${{ github.action_path }}/scripts/remove_duplicate_candidate_label.cjs
           with:
               github-token: ${{ inputs.github-token }}
               script: |

package/plugins/pr-review/README.md

@@ -69,7 +69,7 @@ Add the following secrets in your repository settings (**Settings → Secrets an
 | `GITHUB_TOKEN` | Auto | Provided automatically by GitHub Actions |
 | `LMNR_SKILLS_API_KEY` | No | Laminar API key (org-level secret; mapped to `LMNR_PROJECT_API_KEY` env var in workflows) |
 
-**Note**: For repositories that need to post review comments from a bot account, use `ALLHANDS_BOT_GITHUB_PAT` instead of `GITHUB_TOKEN`.
+**Note**: To post review comments from a bot account instead of `GITHUB_TOKEN`, use a bot token scoped to the repository's trust boundary. On **public** repositories, use `OPENHANDS_BOT_GITHUB_PAT_PUBLIC` — a fine-grained token limited to public repositories. On **private** repositories, use a bot token scoped to that repository. Never give a public repository a token that can reach private repositories.
 
 ### 3. Customize the Workflow (Optional)
 

package/plugins/qa-changes/action.yml

@@ -119,6 +119,8 @@ runs:
       env:
         LLM_API_KEY: ${{ inputs.llm-api-key }}
         GITHUB_TOKEN: ${{ inputs.github-token }}
+        GITHUB_EVENT_PULL_REQUEST_TITLE: ${{ github.event.pull_request.title }}
+        INPUTS_LLM_MODEL: ${{ inputs.llm-model }}
       run: |
         if [ -z "$LLM_API_KEY" ]; then
           echo "Error: llm-api-key is required."
@@ -130,9 +132,9 @@ runs:
         fi
 
         echo "PR Number: ${{ github.event.pull_request.number }}"
-        echo "PR Title: ${{ github.event.pull_request.title }}"
+        echo "PR Title: $GITHUB_EVENT_PULL_REQUEST_TITLE"
         echo "Repository: ${{ github.repository }}"
-        echo "LLM model: ${{ inputs.llm-model }}"
+        echo "LLM model: $INPUTS_LLM_MODEL"
 
     - name: Run QA validation
       if: steps.preflight.outputs.skip != 'true'

package/plugins/release-notes/action.yml

@@ -109,9 +109,10 @@ runs:
           shell: bash
           env:
               GITHUB_TOKEN: ${{ inputs.github-token }}
+              INPUTS_TAG: ${{ inputs.tag }}
           run: |
               if [ -f release_notes.md ]; then
-                echo "Updating release notes for tag ${{ inputs.tag }}"
-                gh release edit "${{ inputs.tag }}" --notes-file release_notes.md || \
+                echo "Updating release notes for tag $INPUTS_TAG"
+                gh release edit "$INPUTS_TAG" --notes-file release_notes.md || \
                   echo "Note: Could not update release. Release may not exist yet."
               fi

package/plugins/release-notes/workflows/release-notes.yml

@@ -38,11 +38,14 @@ jobs:
 
             - name: Determine tag
               id: get-tag
+              env:
+                GITHUB_EVENT_INPUTS_TAG: ${{ github.event.inputs.tag }}
+                GITHUB_REF_NAME: ${{ github.ref_name }}
               run: |
                   if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then
-                    echo "tag=${{ github.event.inputs.tag }}" >> $GITHUB_OUTPUT
+                    echo "tag=$GITHUB_EVENT_INPUTS_TAG" >> $GITHUB_OUTPUT
                   else
-                    echo "tag=${{ github.ref_name }}" >> $GITHUB_OUTPUT
+                    echo "tag=$GITHUB_REF_NAME" >> $GITHUB_OUTPUT
                   fi
 
             - name: Generate Release Notes
@@ -57,10 +60,13 @@ jobs:
                   github-token: ${{ secrets.GITHUB_TOKEN }}
 
             - name: Display generated notes
+              env:
+                TAG: ${{ steps.get-tag.outputs.tag }}
+                PREVIOUS_TAG: ${{ steps.release-notes.outputs.previous-tag }}
               run: |
-                  echo "## Release Notes for ${{ steps.get-tag.outputs.tag }}"
+                  echo "## Release Notes for $TAG"
                   echo ""
-                  echo "Previous tag: ${{ steps.release-notes.outputs.previous-tag }}"
+                  echo "Previous tag: $PREVIOUS_TAG"
                   echo "Commits: ${{ steps.release-notes.outputs.commit-count }}"
                   echo "Contributors: ${{ steps.release-notes.outputs.contributor-count }}"
                   echo "New contributors: ${{ steps.release-notes.outputs.new-contributor-count }}"

package/plugins/vulnerability-remediation/README.md

@@ -90,12 +90,14 @@ on:
 
 ### Optional: Use a Bot Account
 
-For better PR attribution, use a bot PAT:
+For better PR attribution, use a bot PAT scoped to the repository's trust boundary. On **public** repositories, use the public-scoped token:
 
 ```yaml
-github-token: ${{ secrets.ALLHANDS_BOT_GITHUB_PAT || secrets.GITHUB_TOKEN }}
+github-token: ${{ secrets.OPENHANDS_BOT_GITHUB_PAT_PUBLIC || secrets.GITHUB_TOKEN }}
 ```
 
+On **private** repositories, use a bot token scoped to that repository instead. Never give a public repository a token that can reach private repositories.
+
 ## Usage
 
 ### Automatic Scheduled Scans

package/plugins/vulnerability-remediation/action.yml

@@ -96,6 +96,10 @@ runs:
           env:
               LLM_API_KEY: ${{ inputs.llm-api-key }}
               GITHUB_TOKEN: ${{ inputs.github-token }}
+              INPUTS_EXTENSIONS_VERSION: ${{ inputs.extensions-version }}
+              INPUTS_LLM_MODEL: ${{ inputs.llm-model }}
+              INPUTS_SEVERITY_THRESHOLD: ${{ inputs.severity-threshold }}
+              INPUTS_MAX_VULNERABILITIES: ${{ inputs.max-vulnerabilities }}
           run: |
               if [ -z "$LLM_API_KEY" ]; then
                 echo "Error: llm-api-key is required."
@@ -108,10 +112,10 @@ runs:
               fi
 
               echo "Repository: ${{ github.repository }}"
-              echo "Extensions Version: ${{ inputs.extensions-version }}"
-              echo "LLM Model: ${{ inputs.llm-model }}"
-              echo "Severity Threshold: ${{ inputs.severity-threshold }}"
-              echo "Max Vulnerabilities: ${{ inputs.max-vulnerabilities }}"
+              echo "Extensions Version: $INPUTS_EXTENSIONS_VERSION"
+              echo "LLM Model: $INPUTS_LLM_MODEL"
+              echo "Severity Threshold: $INPUTS_SEVERITY_THRESHOLD"
+              echo "Max Vulnerabilities: $INPUTS_MAX_VULNERABILITIES"
 
         - name: Run vulnerability scan
           id: scan

package/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "extensions"
-version = "0.3.0"
+version = "0.4.1"
 description = "OpenHands extensions, plugins, and skills"
 requires-python = ">=3.12"
 

package/scripts/sync_extensions.py

@@ -143,7 +143,8 @@ def collect_needed_commands() -> list[CommandSpec]:
             meta = parse_frontmatter(skill_md.read_text())
             desc = str(meta.get("description", ""))
             for trigger in slash_triggers(meta):
-                cmd_name = trigger.lstrip("/")
+                # Replace colons with dashes for cross-platform filename compatibility
+                cmd_name = trigger.lstrip("/").replace(":", "-")
                 cmd_path = skill_dir / "commands" / f"{cmd_name}.md"
                 needed.append(CommandSpec(path=cmd_path, trigger=trigger, description=desc))
     return needed

package/skills/github-actions/.plugin/plugin.json

@@ -0,0 +1,19 @@
+{
+  "name": "github-actions",
+  "version": "1.0.0",
+  "description": "Create, debug, and test GitHub Actions workflows and custom actions. Use when building CI/CD pipelines, automating workflows, or troubleshooting GitHub Actions.",
+  "author": {
+    "name": "OpenHands",
+    "email": "contact@all-hands.dev"
+  },
+  "homepage": "https://github.com/OpenHands/extensions",
+  "repository": "https://github.com/OpenHands/extensions",
+  "license": "MIT",
+  "keywords": [
+    "github-actions",
+    "workflows",
+    "ci-cd",
+    "automation",
+    "actions"
+  ]
+}

package/skills/github-actions/README.md

@@ -0,0 +1,190 @@
+# GitHub Actions Skill
+
+A skill focused on **effectiveness** when working with GitHub Actions — monitoring runs, reading logs, and developing actions with confidence rather than guessing.
+
+## Overview
+
+This skill provides guidance for:
+- Creating and structuring workflows
+- Building custom composite and reusable actions
+- Testing actions locally (before burning CI minutes) and in CI
+- Debugging failed workflows from real evidence (logs), not assumptions
+- Avoiding common pitfalls around permissions, secrets, and fork PRs
+
+## When to Use This Skill
+
+- Creating new GitHub Actions workflows
+- Building custom composite or reusable actions
+- Debugging workflow failures
+- Setting up CI/CD pipelines
+- Troubleshooting permission or secret issues
+- Testing actions before merging to main
+
+## Cost Awareness
+
+Every workflow run consumes CI minutes (billed minutes on private repos, shared capacity on public ones).
+Plan before you push:
+
+- Prefer one targeted commit that exercises the change over multiple speculative pushes
+- Use `workflow_dispatch` with inputs to manually trigger only what you need
+- Use `paths:` filters and `if:` conditions so jobs only run when relevant
+- Run with `act` locally before opening a PR when feasible
+- Cancel obsolete runs with `concurrency:` groups (don't pay for runs you've already invalidated)
+- Use the smallest matrix that proves the change works; expand only if needed
+
+## Develop With Confidence: The Loop
+
+Don't change → push → hope. Use this loop:
+
+1. **Read** the existing workflow / action carefully. Note triggers, permissions, inputs, env, and secrets.
+2. **Reproduce locally** with `act` when possible (see below).
+3. **Add visibility** — debug steps that print non-secret inputs, refs, and intermediate state.
+4. **Push a single focused commit**, then watch the run live.
+5. **Read the full failed-job log** (not just the summary) before editing.
+6. **Form a hypothesis from the log**, change the smallest thing that tests it, push, watch again.
+
+## Monitoring Runs With `gh`
+
+```bash
+# Watch the most recent run from the current branch in real time
+gh run watch
+
+# Watch a specific run
+gh run watch <run-id>
+
+# Auto-refresh PR checks until they finish (every 10s)
+gh pr checks <pr-number> --watch --interval 10
+
+# List recent runs for the repo / branch
+gh run list --branch <branch> --limit 10
+
+# Get the run ID for the latest run on a branch
+gh run list --branch <branch> --limit 1 --json databaseId --jq '.[0].databaseId'
+```
+
+## Reading Logs (Don't Guess)
+
+```bash
+# Full log for a run
+gh run view <run-id> --log
+
+# Just the failed steps (much shorter)
+gh run view <run-id> --log-failed
+
+# Log for a specific job (useful for matrix builds)
+gh run view <run-id> --log --job <job-id>
+
+# List jobs for a run to find the job ID
+gh run view <run-id> --json jobs --jq '.jobs[] | {id, name, conclusion}'
+
+# Rerun only the failed jobs (avoid paying to rerun green ones)
+gh run rerun <run-id> --failed
+```
+
+When a step fails, look for:
+- The exact command that exited non-zero (above the `##[error]` line)
+- The shell — bash on Linux, `pwsh` on Windows runners — error messages differ
+- Values printed by your debug step; compare against what the workflow *thought* it was passing in
+
+## Adding Visibility to Actions
+
+When creating a new action or hitting a tricky bug, add debug steps. Don't leave them in indefinitely — remove or guard them with `if: runner.debug == '1'` once the issue is understood.
+
+```yaml
+steps:
+  # Print non-secret inputs and context at the start
+  - name: Debug - inputs and context
+    if: runner.debug == '1' || inputs.debug == 'true'
+    run: |
+      echo "Event: ${{ github.event_name }}"
+      echo "Ref:   ${{ github.ref }}"
+      echo "SHA:   ${{ github.sha }}"
+      echo "Actor: ${{ github.actor }}"
+      echo "PWD:   $(pwd)"
+      echo "Input.my-param: ${{ inputs.my-param }}"
+      echo "Files:"
+      ls -la
+
+  # ... your real steps ...
+
+  # Verify outcome before the job ends
+  - name: Debug - verify outputs
+    if: always() && (runner.debug == '1' || inputs.debug == 'true')
+    run: |
+      echo "Generated files:"
+      ls -la dist/ || echo "dist/ not found"
+```
+
+To enable `runner.debug == '1'` for a single run, re-run the workflow with **"Enable debug logging"** checked, or set the repo secret `ACTIONS_RUNNER_DEBUG=true`.
+
+**Never** echo `${{ secrets.* }}` — GitHub masks them, but encoded forms (base64, hex, JSON-wrapped) can leak through.
+
+## Testing Locally With `act`
+
+`act` ([nektos/act](https://github.com/nektos/act)) runs workflows in Docker locally (Docker must be installed and running). Use it to iterate without burning CI minutes.
+
+```bash
+# Run the default push event
+act
+
+# Simulate a pull_request event
+act pull_request
+
+# Run a specific job
+act -j build
+
+# Pass secrets
+act -s GITHUB_TOKEN="$GITHUB_TOKEN"
+
+# Use a larger image closer to GitHub's runner
+act -P ubuntu-latest=catthehacker/ubuntu:full-latest
+```
+
+Caveats: `act` does not perfectly emulate GitHub's runners. Things that may differ: pre-installed tools, `GITHUB_TOKEN` permissions, OIDC, the `secrets.GITHUB_TOKEN` value, and macOS/Windows runners. Treat green-on-`act` as a strong signal, not a guarantee.
+
+## Testing Custom Actions Requires Merge to Main
+
+A repository-local custom action referenced as `uses: ./.github/actions/my-action` works from any branch, but:
+
+- A custom action published as `uses: owner/repo/action@ref` must have the action's files **on `ref`** to be resolvable
+- `@main` or `@v1` must already exist when the workflow that consumes it runs
+- This is why a brand-new action typically must land on `main` first, then be consumed from feature branches that reference `@main` (or a tag)
+
+If you need to iterate on an action and its consumer together, point `uses:` at a SHA on your branch, or develop the action via the local `./.github/actions/…` path until it's stable.
+
+## Common Pitfalls
+
+1. **Custom action not found from a PR** — the action's ref doesn't exist yet. Merge to `main` (or push a tag), then consume.
+2. **`GITHUB_TOKEN` permissions** — defaults can be read-only. Set `permissions:` explicitly at the workflow or job level.
+3. **`pull_request` vs `pull_request_target`** — `pull_request` runs in the fork's context (no secrets); `pull_request_target` runs with repo secrets against the base — **dangerous** if you check out PR code and execute it. Don't.
+4. **Secrets in fork PRs** — even non-`*_target` workflows hide secrets from forks. Don't design workflows that require secrets to run on community PRs.
+5. **`schedule:` triggers only fire from the default branch** — a `schedule:` trigger added in a PR only fires after it lands on the default branch; `workflow_dispatch` similarly won't appear in the Actions tab UI until merged to default (though it can be triggered via API on any branch); `pull_request`-triggered workflows do run on the PR that introduces them.
+6. **Path filters are OR, not AND** — any matching path triggers; you can't require all paths.
+7. **Matrix `fail-fast: true`** (default) cancels other matrix legs on first failure — turn off when you need full coverage.
+8. **Artifacts** — files don't persist between jobs unless uploaded via `actions/upload-artifact` and downloaded in the consuming job.
+9. **`env:` scope** — env at workflow, job, and step levels all exist. Step-level shadows job-level shadows workflow-level. Surprises follow if you forget.
+10. **Pin versions** — use `@v4` (or better, a SHA) rather than `@main`. Floating refs break builds when upstream changes.
+
+## Best Practices
+
+1. **Pin action versions** — `@v4` or SHA, not `@main`
+2. **Least privilege** — set `permissions:` to the minimum needed
+3. **Debug steps when introducing or debugging** — remove or gate them with `runner.debug` afterward
+4. **Cache dependencies** — `actions/cache` saves real minutes
+5. **Concurrency** — cancel obsolete runs:
+   ```yaml
+   concurrency:
+     group: ${{ github.workflow }}-${{ github.ref }}
+     cancel-in-progress: true
+   ```
+6. **Timeouts** — set `timeout-minutes:` on jobs that can hang
+7. **Fail loudly** — `set -euo pipefail` in non-trivial bash steps
+8. **Document non-obvious triggers/inputs** at the top of the workflow file
+
+## Resources
+
+- [GitHub Actions documentation](https://docs.github.com/en/actions)
+- [`act` — run actions locally](https://github.com/nektos/act)
+- [`gh run` CLI reference](https://cli.github.com/manual/gh_run)
+- [github skill](https://github.com/OpenHands/extensions/tree/main/skills/github) — GitHub API, PRs, issues, and repos
+- [github-pr-review skill](https://github.com/OpenHands/extensions/tree/main/skills/github-pr-review) — post structured code reviews via the GitHub API

package/skills/github-actions/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: github-actions
+description: Create, debug, and test GitHub Actions workflows and custom actions. Use when building CI/CD pipelines, automating workflows, or troubleshooting GitHub Actions.
+triggers:
+- github actions
+- github workflow
+- actions workflow
+- gh actions
+- .github/workflows
+---
+
+# GitHub Actions Guide
+
+## Critical Rules
+
+**Custom Action Deployment:**
+- New custom actions MUST be merged to the main branch before they can be used
+- After the initial merge, they should be tested from feature branches
+
+**Debug Steps:**
+Add debug steps that print non-secret parameters when:
+- Creating a new action, OR
+- Troubleshooting a particularly tricky issue
+
+(Not required for every workflow - use when needed)
+
+## Effectiveness Principles
+
+Actions cost CI minutes. Be deliberate, not iterative:
+
+1. **Monitor, don't poll** - use `gh run watch` / `gh pr checks --watch` to follow runs live
+2. **Read logs, don't guess** - fetch the failed job's log before changing code
+3. **Print actual values** - debug steps reveal the real `inputs`/`github` context, not your assumptions
+4. **Test locally first** - `act` runs workflows on your machine and avoids burning CI minutes
+5. **Plan the smallest reproduction** - one job, minimal matrix, narrow trigger before scaling up
+
+See [README.md](README.md) for the full debugging workflow, `gh` commands, and YAML debug-step examples.
+
+## Key Gotchas
+
+1. **Secrets unavailable in fork PRs** - `pull_request` has no secrets for forks; `pull_request_target` does but **never check out or execute fork PR code inside it** (RCE with write permissions)
+2. **Pin action versions** - Use `@v4` or SHA, not `@main` (prevents breaking changes)
+3. **Explicit permissions** - Set `permissions:` block for GITHUB_TOKEN operations
+4. **Artifacts for job-to-job data** - Files don't persist between jobs without `upload-artifact`/`download-artifact`