github-repo-monitor

Files (12)

• .claude-plugin
• .codex-plugin
• plugin.json · .plugin/
• README.md
• SKILL.md
• github-monitor-poll.md · commands/
• github-api.md · references/
• state-schema.md · references/
• windows.md · references/
• github_client.py · scripts/
• main.py · scripts/
• test_main.py · tests/

SKILL.md (first lines)

# GitHub Repository Monitor

Create a cron automation that polls a single GitHub repository on a
configurable schedule (default: every minute).
Windows PowerShell equivalents for the setup, packaging, upload, and API-check shell snippets are in `references/windows.md`.

When a comment on an issue or PR contains the **trigger phrase**
(default: `@OpenHands`), and its author is allowed to trigger work, it:

1. Posts a GitHub comment acknowledging the request with a conversation link.
2. Creates an OpenHands conversation pre-loaded with the issue/PR title, body,
   labels, and recent comment history for full context.
3. Lets the agent answer the request, and - when asked to change something and
   `WORK_MODE` is `implement` - do the work on a branch, push it, and update an
   existing pull request instead of opening a second one.
4. Posts a summary GitHub comment when the conversation finishes.

Authorization comes before work. With `AUTHORIZATION = "repo_write"` (the
default) the script asks GitHub for the commenter's permission on the repository
and acts only when it is `admin`, `maintain`, or `write`; a trigger phrase on a
public repository therefore spends nobody's tokens.

On every subsequent run:
- New trigger comments on an already-tracked issue/PR are forwarded to the
  running conversation (or re-open a previously closed one).
- When a conversation goes idle/finished/error the agent's final response
  is posted back as a GitHub comment.

> **Local mode only.** This automation targets the local OpenHands setup
> (`dev:automation` stack). A cloud/webhook variant is out of scope here.

---

The script imports shared GitHub transport from
`scripts/github_client.py`, installed with this skill. Include it beside
`main.py` when packaging manually, as shown below.

## Prerequisites

### Required secret

Verify that the following secret is set in **OpenHands Settings → Secrets**
before proceeding:

| Secret name | Token type | Minimum permissions |
|---|---|---|
| `GITHUB_PERSONAL_ACCESS_TOKEN` | Classic PAT | `repo` (private repos) or `public_repo` (public repos); add `workflow` if `WORK_MODE` is `implement` and the repository has workflows |
| `GITHUB_PERSONAL_ACCESS_TOKEN` | Fine-grained PAT | Issues: Read and Write; Contents: Read and Write and Pull requests: Read and Write when `WORK_MODE` is `implement`; Metadata: Read for the permission check |

Check with:
```bash
curl -s https://api.github.com/user \
  -H "Authorization: Bearer $GITHUB_PERSONAL_ACCESS_TOKEN" \
  -H "Accept: application/vnd.github+json" \
  | python3 -c "import json,sys; d=json.load(sys.stdin); print(d.get('login') or d.get('message'))"
```

If the token is missing, inform the user and stop — the automation cannot
function without GitHub credentials.

### Optional secret

| Secret name | Default | Purpose |
|---|---|---|
| `OPENHANDS_URL` | `http://localhost:8000` | Base URL used to build conversation links in GitHub comments |

---

## Setup Workflow

Follow these steps in order.

### Step 1  -  Verify GITHUB_PERSONAL_ACCESS_TOKEN

Fetch the secret and run the `curl` check above.

- If the secret is absent: tell the user
  *"GITHUB_PERSONAL_ACCESS_TOKEN is not set. Please add it in OpenHands Settings → Secrets
  (classic PAT with `repo` or `public_repo` scope, or a fine-grained PAT
  with Issues: Read and Write, plus Contents: Read and Write when the agent
  is allowed to implement)."* Then stop.

- If the API returns a non-200 or `{"message": "Bad credentials"}`:
  tell the user the token is invalid and ask them to update it.

### Step 2  -  Collect repository

Ask the user: *"Which GitHub repository should be monitored?
(Format: `owner/repo`, e.g. `microsoft/vscode`)"*

Validate access and write permissions:

```bash
curl -s "https://api.github.com/repos/{owner}/{repo}" \
  -H "Authorization: Bearer $GITHUB_PERSONAL_ACCESS_TOKEN" \
  -H "Accept: application/vnd.github+json" \
  | python3 -c "
import json, sys
d = json.load(sys.stdin)
if 'message' in d:
    print('ERROR:', d['message'])
else:
    perms = d.get('permissions', {})
    print(f\"Accessible. Private: {d.get('private')}. Permissions: {perms}\")
"
```

- If `message: Not Found` or `message: Bad credentials` →
  inform the user and ask them to check the repo name and token.
- If the repo is private and `permissions.push` is `false` →
  inform the user the token does not have write access and comments will fail.
- If the check passes, record `REPO = "{owner}/{repo}"`.

### Step 3  -  Collect trigger phrase

Ask the user: *"What trigger phrase should OpenHands respond to?
(Press Enter to use the default: `@OpenHands`)"*

Accepted values: any non-empty string unlikely to appear by accident. The alias

From OpenHands/extensions, MIT.

More from OpenHands/extensions