GitHub Repo Monitor

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) 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. Posts a summary GitHub comment when the conversation finishes.

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:

Check with:

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

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)." 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:

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.

Record as TRIGGER_PHRASE. Default: "@openhands".

Step 4 - Collect allowed GitHub logins

Ask the user: "Which GitHub users may trigger this automation? Press Enter to allow only the authenticated GITHUB_PERSONAL_ACCESS_TOKEN owner. You may also provide comma-separated GitHub logins, or * to allow any non-bot commenter on the monitored repository."

Map the answer to ALLOWED_GITHUB_LOGINS:

Default to token-owner-only unless the user explicitly chooses a broader allowlist. Record as ALLOWED_GITHUB_LOGINS.

Step 5 - Collect event types

Ask the user: "Which event types should be monitored? Choose one or more: 1. Issue and PR comments (default) 2. PR inline review comments 3. Both (Press Enter to accept the default: issue and PR comments.)"

Map the choice to the EVENT_TYPES list:

Step 6 - Collect cron schedule

Ask the user: "How often should the automation poll GitHub? (Press Enter for the default: every minute. Use a cron expression for a different interval, e.g.: */5 * * * * = every 5 minutes, 0 * * * * = every hour)"

Default: * * * * * (every minute).

Record as CRON_SCHEDULE.

Step 7 - Generate the automation script

Read scripts/main.py from this skill's directory. Apply exactly five constant substitutions near the top of the file:

Run these commands from this skill's directory and write the customised script to a temporary build directory:

mkdir -p /tmp/github-monitor-build
cp -L scripts/github_client.py /tmp/github-monitor-build/github_client.py
# (write the customised main.py to /tmp/github-monitor-build/main.py)

Validate syntax before packaging:

python3 -m py_compile /tmp/github-monitor-build/main.py && echo "Syntax OK"

Fix any syntax errors before proceeding.