WASM tool for GitHub integration. It covers repositories, issues, pull requests, search, branches, file reads and writes, releases, and workflows.
- Repositories - Get repo details, list user repos, create repositories
- Search - Search repositories, code, and issues/PRs
- Branches - List branches and create new branches from an existing ref
- Fork - Fork repositories
- 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 and create/update/delete repository files
- Releases - List releases and create new releases
- Workflows - Trigger GitHub Actions, check run status
Preferred: configure GitHub OAuth app credentials for browser auth:
-
Create a GitHub OAuth app at https://github.com/settings/apps
-
Set the callback URL to your IronClaw OAuth callback URL
-
Export:
export GITHUB_OAUTH_CLIENT_ID=... export GITHUB_OAUTH_CLIENT_SECRET=...
-
Run:
ironclaw tool auth github
IronClaw will open the browser OAuth flow and store the resulting github_token.
Fallback: use a Personal Access Token if you do not want to run an OAuth app:
-
Create a GitHub Personal Access Token at https://github.com/settings/tokens
-
Recommended scopes:
repo,workflow,read:org -
Store the token:
ironclaw secret set github_token YOUR_TOKEN
{
"action": "get_repo",
"owner": "nearai",
"repo": "ironclaw"
}{
"action": "create_repo",
"name": "infra-playground",
"description": "Scratch repo for release automation",
"private": true,
"auto_init": true
}{
"action": "list_issues",
"owner": "nearai",
"repo": "ironclaw",
"state": "open",
"limit": 10
}{
"action": "create_issue",
"owner": "nearai",
"repo": "ironclaw",
"title": "Bug: Something is broken",
"body": "Detailed description...",
"labels": ["bug", "help wanted"]
}{
"action": "list_pull_requests",
"owner": "nearai",
"repo": "ironclaw",
"state": "open",
"limit": 5
}{
"action": "search_code",
"query": "repo:nearai/ironclaw tool_info",
"limit": 5
}{
"action": "search_issues_pull_requests",
"query": "repo:nearai/ironclaw is:pr label:bug",
"limit": 10
}{
"action": "create_pr_review",
"owner": "nearai",
"repo": "ironclaw",
"pr_number": 42,
"body": "LGTM! Great work.",
"event": "APPROVE"
}{
"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."
}{
"action": "merge_pull_request",
"owner": "nearai",
"repo": "ironclaw",
"pr_number": 42,
"merge_method": "squash"
}{
"action": "list_issue_comments",
"owner": "nearai",
"repo": "ironclaw",
"issue_number": 42,
"limit": 10
}{
"action": "create_issue_comment",
"owner": "nearai",
"repo": "ironclaw",
"issue_number": 42,
"body": "Thanks for reporting this!"
}{
"action": "list_pull_request_comments",
"owner": "nearai",
"repo": "ironclaw",
"pr_number": 42,
"limit": 30
}{
"action": "reply_pull_request_comment",
"owner": "nearai",
"repo": "ironclaw",
"comment_id": 123456789,
"body": "Fixed in the latest commit."
}{
"action": "get_pull_request_reviews",
"owner": "nearai",
"repo": "ironclaw",
"pr_number": 42
}{
"action": "get_combined_status",
"owner": "nearai",
"repo": "ironclaw",
"ref": "main"
}{
"action": "get_file_content",
"owner": "nearai",
"repo": "ironclaw",
"path": "README.md",
"ref": "main"
}{
"action": "create_or_update_file",
"owner": "nearai",
"repo": "ironclaw",
"path": "docs/example.txt",
"message": "docs: add example",
"content": "Hello from IronClaw"
}When updating an existing file, include the current blob sha.
{
"action": "delete_file",
"owner": "nearai",
"repo": "ironclaw",
"path": "docs/example.txt",
"message": "docs: remove example",
"sha": "0123456789abcdef0123456789abcdef01234567"
}{
"action": "list_branches",
"owner": "nearai",
"repo": "ironclaw",
"limit": 20
}{
"action": "fork_repo",
"owner": "nearai",
"repo": "ironclaw",
"organization": "my-org",
"name": "ironclaw-fork",
"default_branch_only": true
}organization, name, and default_branch_only are optional. Omit organization to fork into the authenticated user's account.
{
"action": "create_branch",
"owner": "nearai",
"repo": "ironclaw",
"branch": "feature/github-tool-audit",
"from_ref": "main"
}{
"action": "list_releases",
"owner": "nearai",
"repo": "ironclaw",
"limit": 10
}{
"action": "create_release",
"owner": "nearai",
"repo": "ironclaw",
"tag_name": "v1.2.3",
"name": "v1.2.3",
"generate_release_notes": true
}{
"action": "trigger_workflow",
"owner": "nearai",
"repo": "ironclaw",
"workflow_id": "ci.yml",
"ref": "main",
"inputs": {
"environment": "staging"
}
}{
"action": "get_workflow_runs",
"owner": "nearai",
"repo": "ironclaw",
"limit": 5
}{
"action": "get_workflow_runs",
"owner": "nearai",
"repo": "ironclaw",
"limit": 5,
"page": 2
}Errors are returned as strings in the error field of the response.
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 event: 'INVALID'. Must be one of: APPROVE, REQUEST_CHANGES, COMMENT
GitHub token not found in secret store. Set it with: ironclaw secret set github_token <token>...
- Check that the
ownerandrepoare correct. - Ensure the
github_tokenhas access to the repository (especially for private repos). - Verify the token scopes include
repoandread:org.
- The token might be invalid or expired.
- Update the token:
ironclaw secret set github_token NEW_TOKEN.
- 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).
cd tools-src/github
cargo build --target wasm32-wasi --releaseMIT/Apache-2.0