---
name: github
description: |
  Official GitHub skill for OCLAWMA. Comprehensive GitHub operations including
  repository management, pull requests, issues, releases, and GitHub Actions
  workflow monitoring. Use this skill when:
  (1) Managing repositories: list, create, search, get details
  (2) Pull requests: list, create, review, merge, close, view files
  (3) Issues: list, create, update, search, add comments, manage labels
  (4) GitHub Actions: monitor workflows, trigger runs, view logs, artifacts
  (5) Releases: list, create, manage assets
  (6) Code operations: search, get file contents, compare branches
  (7) Collaboration: manage collaborators and permissions
metadata:
  author: OpenClaw Team
  version: "1.0.0"
  category: devops
  tags:
    - github
    - git
    - repository
    - pull-request
    - issues
    - actions
    - ci-cd
    - collaboration
---

# GitHub Skill for OCLAWMA

Official GitHub skill providing comprehensive repository management, pull request operations, issue tracking, and GitHub Actions monitoring.

## Authentication

Set one of these environment variables:
```bash
export GITHUB_TOKEN="ghp_your_token_here"
# or
export GH_TOKEN="ghp_your_token_here"
```

### Required Token Scopes

| Feature | Required Scopes |
|---------|-----------------|
| Repository read | `repo` (private repos) or public access |
| Repository write | `repo` |
| Actions | `repo`, `workflow` |
| Issues/PRs | `repo` |
| Releases | `repo` |
| Collaborators | `repo`, `read:org` |

### Creating a Token

1. Go to GitHub Settings → Developer settings → Personal access tokens
2. Generate new token (classic) or fine-grained token
3. Select required scopes
4. Copy and set as environment variable

## Tools Reference

### Repository Operations

#### list_repos
List repositories for a user or organization.

```yaml
parameters:
  owner: {type: string, required: false, description: "Username or org name"}
  type: {type: string, default: "owner", enum: ["all", "owner", "member"]}
  sort: {type: string, default: "updated", enum: ["created", "updated", "pushed", "full_name"]}
  limit: {type: integer, default: 30}
```

**Example:**
```python
# List authenticated user's repos
result = await registry.execute_tool("github", "list_repos")

# List organization's repos
result = await registry.execute_tool("github", "list_repos", owner="openclaw")
```

#### get_repo
Get detailed repository information.

```yaml
parameters:
  owner: {type: string, required: true}
  repo: {type: string, required: true}
```

#### create_repo
Create a new repository.

```yaml
parameters:
  name: {type: string, required: true}
  description: {type: string, default: ""}
  private: {type: boolean, default: false}
  auto_init: {type: boolean, default: false}
  gitignore_template: {type: string, required: false}
  license_template: {type: string, required: false}
  org: {type: string, required: false, description: "Create in organization"}
```

#### search_repos
Search repositories across GitHub.

```yaml
parameters:
  query: {type: string, required: true, description: "GitHub search query"}
  sort: {type: string, default: "updated", enum: ["stars", "forks", "updated"]}
  order: {type: string, default: "desc", enum: ["asc", "desc"]}
  limit: {type: integer, default: 30}
```

**Example:**
```python
result = await registry.execute_tool(
    "github", "search_repos",
    query="language:python stars:>1000 topic:machine-learning"
)
```

### Pull Request Operations

#### list_prs
List pull requests for a repository.

```yaml
parameters:
  owner: {type: string, required: true}
  repo: {type: string, required: true}
  state: {type: string, default: "open", enum: ["open", "closed", "all"]}
  head: {type: string, required: false, description: "Filter by head branch"}
  base: {type: string, required: false, description: "Filter by base branch"}
  sort: {type: string, default: "updated", enum: ["created", "updated", "popularity", "long-running"]}
  limit: {type: integer, default: 30}
```

#### get_pr
Get detailed pull request information.

```yaml
parameters:
  owner: {type: string, required: true}
  repo: {type: string, required: true}
  number: {type: integer, required: true}
```

#### create_pr
Create a new pull request.

```yaml
parameters:
  owner: {type: string, required: true}
  repo: {type: string, required: true}
  title: {type: string, required: true}
  head: {type: string, required: true, description: "Source branch"}
  base: {type: string, required: true, description: "Target branch"}
  body: {type: string, default: ""}
  draft: {type: boolean, default: false}
  maintainer_can_modify: {type: boolean, default: true}
```

**Example:**
```python
result = await registry.execute_tool(
    "github", "create_pr",
    owner="openclaw",
    repo="oclawma",
    title="Add new feature",
    head="feature-branch",
    base="main",
    body="This PR adds..."
)
```

#### merge_pr
Merge a pull request.

```yaml
parameters:
  owner: {type: string, required: true}
  repo: {type: string, required: true}
  number: {type: integer, required: true}
  commit_title: {type: string, required: false}
  commit_message: {type: string, required: false}
  sha: {type: string, required: false, description: "SHA to verify"}
  merge_method: {type: string, default: "merge", enum: ["merge", "squash", "rebase"]}
```

#### review_pr
Submit a pull request review.

```yaml
parameters:
  owner: {type: string, required: true}
  repo: {type: string, required: true}
  number: {type: integer, required: true}
  event: {type: string, required: true, enum: ["APPROVE", "REQUEST_CHANGES", "COMMENT"]}
  body: {type: string, default: ""}
  comments: {type: array, required: false, description: "Line-specific comments"}
```

#### list_pr_files
List files changed in a pull request.

```yaml
parameters:
  owner: {type: string, required: true}
  repo: {type: string, required: true}
  number: {type: integer, required: true}
  limit: {type: integer, default: 100}
```

### Issue Operations

#### list_issues
List issues for a repository.

```yaml
parameters:
  owner: {type: string, required: true}
  repo: {type: string, required: true}
  state: {type: string, default: "open", enum: ["open", "closed", "all"]}
  labels: {type: string, required: false, description: "Comma-separated label names"}
  assignee: {type: string, required: false}
  creator: {type: string, required: false}
  milestone: {type: string, required: false}
  sort: {type: string, default: "updated", enum: ["created", "updated", "comments"]}
  limit: {type: integer, default: 30}
```

#### create_issue
Create a new issue.

```yaml
parameters:
  owner: {type: string, required: true}
  repo: {type: string, required: true}
  title: {type: string, required: true}
  body: {type: string, default: ""}
  labels: {type: array, required: false}
  assignees: {type: array, required: false}
  milestone: {type: integer, required: false}
```

#### search_issues
Search issues and pull requests.

```yaml
parameters:
  query: {type: string, required: true, description: "GitHub search syntax"}
  sort: {type: string, default: "updated", enum: ["comments", "reactions", "created", "updated"]}
  order: {type: string, default: "desc"}
  limit: {type: integer, default: 30}
```

**Example:**
```python
# Find open bugs in a repo
result = await registry.execute_tool(
    "github", "search_issues",
    query="is:open is:issue label:bug repo:openclaw/oclawma"
)

# Find issues assigned to me
result = await registry.execute_tool(
    "github", "search_issues",
    query="is:open assignee:@me"
)
```

#### add_issue_comment
Add a comment to an issue or PR.

```yaml
parameters:
  owner: {type: string, required: true}
  repo: {type: string, required: true}
  number: {type: integer, required: true}
  body: {type: string, required: true}
```

### Label Operations

#### list_labels
List labels for a repository.

#### create_label
Create a new label.

```yaml
parameters:
  owner: {type: string, required: true}
  repo: {type: string, required: true}
  name: {type: string, required: true}
  color: {type: string, required: true, description: "Hex color without #"}
  description: {type: string, default: ""}
```

#### add_labels
Add labels to an issue or PR.

#### remove_label
Remove a label from an issue or PR.

### GitHub Actions

#### list_workflows
List GitHub Actions workflows.

```yaml
parameters:
  owner: {type: string, required: true}
  repo: {type: string, required: true}
```

#### list_workflow_runs
List workflow runs.

```yaml
parameters:
  owner: {type: string, required: true}
  repo: {type: string, required: true}
  workflow_id: {type: string, required: false, description: "Filter by workflow"}
  branch: {type: string, required: false}
  event: {type: string, required: false, description: "push, pull_request, etc."}
  status: {type: string, required: false, description: "queued, completed, in_progress"}
  limit: {type: integer, default: 30}
```

**Example:**
```python
# Check recent runs on main branch
result = await registry.execute_tool(
    "github", "list_workflow_runs",
    owner="openclaw",
    repo="oclawma",
    branch="main",
    limit=10
)
```

#### get_workflow_run
Get detailed workflow run information.

```yaml
parameters:
  owner: {type: string, required: true}
  repo: {type: string, required: true}
  run_id: {type: integer, required: true}
```

#### trigger_workflow
Trigger a workflow dispatch event.

```yaml
parameters:
  owner: {type: string, required: true}
  repo: {type: string, required: true}
  workflow_id: {type: string, required: true, description: "Filename or ID"}
  ref: {type: string, required: true, description: "Branch, tag, or SHA"}
  inputs: {type: object, required: false, description: "Workflow inputs"}
```

**Example:**
```python
result = await registry.execute_tool(
    "github", "trigger_workflow",
    owner="openclaw",
    repo="oclawma",
    workflow_id="deploy.yml",
    ref="main",
    inputs={"environment": "staging", "version": "1.2.3"}
)
```

#### rerun_workflow
Rerun a workflow run.

```yaml
parameters:
  owner: {type: string, required: true}
  repo: {type: string, required: true}
  run_id: {type: integer, required: true}
  failed_only: {type: boolean, default: false}
```

#### cancel_workflow
Cancel a workflow run.

#### get_run_logs
Get workflow run logs (returns download URL).

#### list_run_artifacts
List artifacts from a workflow run.

### Release Operations

#### list_releases
List releases for a repository.

#### get_release
Get a specific release.

```yaml
parameters:
  owner: {type: string, required: true}
  repo: {type: string, required: true}
  tag: {type: string, required: false}
  release_id: {type: integer, required: false}
```

#### create_release
Create a new release.

```yaml
parameters:
  owner: {type: string, required: true}
  repo: {type: string, required: true}
  tag_name: {type: string, required: true}
  name: {type: string, required: false}
  body: {type: string, default: ""}
  target_commitish: {type: string, default: "main"}
  draft: {type: boolean, default: false}
  prerelease: {type: boolean, default: false}
  generate_release_notes: {type: boolean, default: false}
```

**Example:**
```python
result = await registry.execute_tool(
    "github", "create_release",
    owner="openclaw",
    repo="oclawma",
    tag_name="v1.0.0",
    name="Version 1.0.0",
    body="Release notes...",
    generate_release_notes=True
)
```

### Code Operations

#### get_file
Get file contents from a repository.

```yaml
parameters:
  owner: {type: string, required: true}
  repo: {type: string, required: true}
  path: {type: string, required: true}
  ref: {type: string, default: "main"}
```

#### get_readme
Get README contents.

#### list_branches
List repository branches.

```yaml
parameters:
  owner: {type: string, required: true}
  repo: {type: string, required: true}
  protected_only: {type: boolean, default: false}
  limit: {type: integer, default: 100}
```

#### compare_branches
Compare two branches or commits.

```yaml
parameters:
  owner: {type: string, required: true}
  repo: {type: string, required: true}
  base: {type: string, required: true}
  head: {type: string, required: true}
```

#### search_code
Search code across GitHub.

```yaml
parameters:
  query: {type: string, required: true}
  sort: {type: string, default: "indexed"}
  order: {type: string, default: "desc"}
  limit: {type: integer, default: 30}
```

### Collaboration

#### list_collaborators
List repository collaborators.

#### add_collaborator
Add a collaborator.

```yaml
parameters:
  owner: {type: string, required: true}
  repo: {type: string, required: true}
  username: {type: string, required: true}
  permission: {type: string, default: "push", enum: ["pull", "push", "admin", "maintain", "triage"]}
```

#### remove_collaborator
Remove a collaborator.

### Utility

#### rate_limit
Check API rate limit status.

#### whoami
Get authenticated user information.

## Common Workflows

### Review and Merge a PR

```python
# 1. Get PR details
pr = await registry.execute_tool("github", "get_pr", owner="org", repo="repo", number=42)

# 2. Review the PR files
files = await registry.execute_tool("github", "list_pr_files", owner="org", repo="repo", number=42)

# 3. Approve the PR
review = await registry.execute_tool(
    "github", "review_pr",
    owner="org", repo="repo", number=42,
    event="APPROVE", body="LGTM!"
)

# 4. Merge the PR
merge = await registry.execute_tool(
    "github", "merge_pr",
    owner="org", repo="repo", number=42,
    merge_method="squash"
)
```

### Create and Track an Issue

```python
# Create issue
issue = await registry.execute_tool(
    "github", "create_issue",
    owner="org", repo="repo",
    title="Bug: Something is broken",
    body="Description of the bug...",
    labels=["bug", "high-priority"],
    assignees=["username"]
)

# Add comment
await registry.execute_tool(
    "github", "add_issue_comment",
    owner="org", repo="repo",
    number=issue["data"]["number"],
    body="Update: Working on this..."
)

# Close issue when resolved
await registry.execute_tool(
    "github", "close_issue",
    owner="org", repo="repo",
    number=issue["data"]["number"]
)
```

### Monitor CI/CD Status

```python
# Check workflow runs
runs = await registry.execute_tool(
    "github", "list_workflow_runs",
    owner="org", repo="repo",
    workflow_id="ci.yml",
    branch="main",
    limit=5
)

# Get details on a specific run
run = await registry.execute_tool(
    "github", "get_workflow_run",
    owner="org", repo="repo",
    run_id=runs["data"][0]["id"]
)

# Rerun if failed
if run["data"]["conclusion"] == "failure":
    await registry.execute_tool(
        "github", "rerun_workflow",
        owner="org", repo="repo",
        run_id=run["data"]["id"]
    )
```

## Error Handling

All tools return standardized result dictionaries:

```python
{
    "success": True/False,
    "data": {...},  # On success
    "error": "...",  # On failure
    "status_code": 400,  # HTTP status if applicable
}
```

### Common Errors

| Error | Meaning | Solution |
|-------|---------|----------|
| `Bad credentials` | Invalid token | Check GITHUB_TOKEN |
| `Not Found` | Resource doesn't exist | Verify owner/repo names |
| `Validation Failed` | Invalid parameters | Check required fields |
| `rate limit exceeded` | API limit reached | Wait for reset or use auth |

## Rate Limits

| Authentication | Requests/Hour |
|----------------|---------------|
| Unauthenticated | 60 |
| Authenticated | 5,000 |
| GitHub App | 15,000+ |

Use the `rate_limit` tool to check your current status.

## Installation

```bash
pip install oclawma-skill-github
```

## Development

```bash
git clone https://github.com/openclaw/oclawma-skill-github.git
cd oclawma-skill-github
pip install -e ".[dev]"
pytest
```

## License

MIT License - Part of the OCLAWMA ecosystem
