optimclaw/tools-src/github/README.md

GitHub Tool for IronClaw

WASM tool for GitHub integration - manage repos, issues, PRs, and workflows.

Features

• Repository Info - Get repo details, list user repos
• Issues - List/create/get issues, list/add issue comments
• Pull Requests - List/create/get PRs, review files, create reviews, list/reply review comments, merge PRs
• File Content - Read files from repos
• Workflows - Trigger GitHub Actions, check run status

Setup

1. Create a GitHub Personal Access Token at https://github.com/settings/tokens

2. Required scopes: repo, workflow, read:org

3. Store the token:

   ironclaw secret set github_token YOUR_TOKEN
   

Usage Examples

Get Repository Info

{
  "action": "get_repo",
  "owner": "nearai",
  "repo": "ironclaw"
}

List Open Issues

{
  "action": "list_issues",
  "owner": "nearai",
  "repo": "ironclaw",
  "state": "open",
  "limit": 10
}

Create Issue

{
  "action": "create_issue",
  "owner": "nearai",
  "repo": "ironclaw",
  "title": "Bug: Something is broken",
  "body": "Detailed description...",
  "labels": ["bug", "help wanted"]
}

List Pull Requests

{
  "action": "list_pull_requests",
  "owner": "nearai",
  "repo": "ironclaw",
  "state": "open",
  "limit": 5
}

Review PR

{
  "action": "create_pr_review",
  "owner": "nearai",
  "repo": "ironclaw",
  "pr_number": 42,
  "body": "LGTM! Great work.",
  "event": "APPROVE"
}

Create Pull Request

{
  "action": "create_pull_request",
  "owner": "nearai",
  "repo": "ironclaw",
  "title": "feat: add event-driven routines",
  "head": "feat/event-routines",
  "base": "main",
  "body": "Implements system_event trigger + event_emit tool."
}

Merge Pull Request

{
  "action": "merge_pull_request",
  "owner": "nearai",
  "repo": "ironclaw",
  "pr_number": 42,
  "merge_method": "squash"
}

Get File Content

{
  "action": "get_file_content",
  "owner": "nearai",
  "repo": "ironclaw",
  "path": "README.md",
  "ref": "main"
}

Trigger Workflow

{
  "action": "trigger_workflow",
  "owner": "nearai",
  "repo": "ironclaw",
  "workflow_id": "ci.yml",
  "ref": "main",
  "inputs": {
    "environment": "staging"
  }
}

Check Workflow Runs

{
  "action": "get_workflow_runs",
  "owner": "nearai",
  "repo": "ironclaw",
  "limit": 5
}

List Workflow Runs (Pagination)

{
  "action": "get_workflow_runs",
  "owner": "nearai",
  "repo": "ironclaw",
  "limit": 5,
  "page": 2
}

Error Handling

Errors are returned as strings in the error field of the response.

Rate Limit Exceeded

When the GitHub API rate limit is exceeded (and retries fail), you might see:

GitHub API error 429: { "message": "API rate limit exceeded for user ID ...", ... }

The tool automatically logs warnings when the rate limit is low (<10 remaining) and retries on 429/5xx errors.

Invalid Parameters

Invalid event: 'INVALID'. Must be one of: APPROVE, REQUEST_CHANGES, COMMENT

Missing Token

GitHub token not found in secret store. Set it with: ironclaw secret set github_token <token>...

Troubleshooting

"GitHub API error 404: Not Found"

• Check that the owner and repo are correct.
• Ensure the github_token has access to the repository (especially for private repos).
• Verify the token scopes include repo and read:org.

"GitHub API error 401: Bad credentials"

• The token might be invalid or expired.
• Update the token: ironclaw secret set github_token NEW_TOKEN.

Rate Limiting

• The tool logs a warning when remaining requests drop below 10.
• Check logs for "GitHub API rate limit low".
• If you hit the limit, wait for the reset time (usually 1 hour).

Building

cd tools-src/github
cargo build --target wasm32-wasi --release

License

MIT/Apache-2.0