# OCLAWMA Skill: GitHub

Official GitHub skill for [OCLAWMA](https://github.com/openclaw/oclawma) providing comprehensive repository management, pull request operations, issue tracking, and GitHub Actions workflow monitoring.

## Features

- **Repository Operations** - List, create, search repositories; get repo details and statistics
- **Pull Request Management** - Create, review, merge, close PRs; view changed files
- **Issue Tracking** - Create, update, search issues; manage labels and milestones
- **GitHub Actions** - Monitor workflows, trigger runs, view logs, download artifacts
- **Release Management** - Create releases, manage release assets
- **Code Search** - Search code across repositories, get file contents
- **Collaboration** - Manage collaborators and repository permissions

## Installation

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

## Authentication

Set your GitHub token as an environment variable:

```bash
export GITHUB_TOKEN="ghp_your_token_here"
# or
export GH_TOKEN="ghp_your_token_here"
```

### 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 based on your needs:
   - `repo` - Full repository access
   - `workflow` - GitHub Actions access
   - `read:org` - Organization read access

## Quick Start

```python
import asyncio
from oclawma.skills import SkillRegistry

async def main():
    # Create registry - skill auto-discovers via entry points
    registry = SkillRegistry()
    
    # List your repositories
    result = await registry.execute_tool("github", "list_repos", limit=10)
    print(result)
    
    # Create a pull request
    result = await registry.execute_tool(
        "github", "create_pr",
        owner="myorg",
        repo="myrepo",
        title="Fix bug in authentication",
        head="fix-auth-bug",
        base="main",
        body="This PR fixes..."
    )
    print(result)
    
    # Check workflow runs
    result = await registry.execute_tool(
        "github", "list_workflow_runs",
        owner="myorg",
        repo="myrepo",
        branch="main",
        limit=5
    )
    print(result)

asyncio.run(main())
```

## Tools Reference

### Repository Operations

| Tool | Description |
|------|-------------|
| `list_repos` | List repositories for a user or organization |
| `get_repo` | Get detailed repository information |
| `create_repo` | Create a new repository |
| `search_repos` | Search repositories across GitHub |
| `get_repo_languages` | Get language statistics for a repository |

### Pull Request Operations

| Tool | Description |
|------|-------------|
| `list_prs` | List pull requests for a repository |
| `get_pr` | Get detailed pull request information |
| `create_pr` | Create a new pull request |
| `update_pr` | Update an existing pull request |
| `merge_pr` | Merge a pull request |
| `close_pr` | Close a pull request without merging |
| `review_pr` | Submit a PR review (approve, request changes, comment) |
| `list_pr_files` | List files changed in a PR |

### Issue Operations

| Tool | Description |
|------|-------------|
| `list_issues` | List issues for a repository |
| `get_issue` | Get detailed issue information |
| `create_issue` | Create a new issue |
| `update_issue` | Update an existing issue |
| `close_issue` | Close an issue |
| `search_issues` | Search issues across GitHub |
| `add_issue_comment` | Add a comment to an issue or PR |

### GitHub Actions

| Tool | Description |
|------|-------------|
| `list_workflows` | List GitHub Actions workflows |
| `list_workflow_runs` | List workflow runs |
| `get_workflow_run` | Get detailed workflow run information |
| `trigger_workflow` | Trigger a workflow dispatch event |
| `rerun_workflow` | Rerun a workflow run |
| `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

| Tool | Description |
|------|-------------|
| `list_releases` | List releases for a repository |
| `get_release` | Get a specific release by tag or ID |
| `create_release` | Create a new release |
| `delete_release` | Delete a release |

### Code Operations

| Tool | Description |
|------|-------------|
| `get_file` | Get file contents from a repository |
| `get_readme` | Get README contents |
| `list_branches` | List repository branches |
| `compare_branches` | Compare two branches or commits |
| `search_code` | Search code across GitHub |

### Collaboration

| Tool | Description |
|------|-------------|
| `list_collaborators` | List repository collaborators |
| `add_collaborator` | Add a collaborator to a repository |
| `remove_collaborator` | Remove a collaborator |

### Utility

| Tool | Description |
|------|-------------|
| `rate_limit` | Check API rate limit status |
| `whoami` | Get authenticated user information |

## Examples

### Review and Merge Workflow

```python
# Review PR files
files = await registry.execute_tool(
    "github", "list_pr_files",
    owner="myorg", repo="myrepo", number=42
)

# Submit review
await registry.execute_tool(
    "github", "review_pr",
    owner="myorg", repo="myrepo", number=42,
    event="APPROVE", body="Looks good!"
)

# Merge with squash
await registry.execute_tool(
    "github", "merge_pr",
    owner="myorg", repo="myrepo", number=42,
    merge_method="squash"
)
```

### Monitor CI/CD

```python
# Check recent runs
runs = await registry.execute_tool(
    "github", "list_workflow_runs",
    owner="myorg", repo="myrepo",
    branch="main", limit=5
)

for run in runs["data"]:
    status = run["status"]
    conclusion = run["conclusion"]
    print(f"Run {run['run_number']}: {status} - {conclusion}")
```

### Create and Manage Issues

```python
# Create issue
issue = await registry.execute_tool(
    "github", "create_issue",
    owner="myorg", repo="myrepo",
    title="Bug: Crash on startup",
    body="Steps to reproduce...",
    labels=["bug", "critical"],
    assignees=["developer1"]
)

# Add update
await registry.execute_tool(
    "github", "add_issue_comment",
    owner="myorg", repo="myrepo",
    number=issue["data"]["number"],
    body="Fixed in commit abc123"
)

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

## Development

```bash
# Clone repository
git clone https://github.com/openclaw/oclawma-skill-github.git
cd oclawma-skill-github

# Setup virtual environment
python -m venv venv
source venv/bin/activate

# Install in development mode
pip install -e ".[dev]"

# Run tests
pytest

# Run linting
black src tests
ruff check src tests
mypy src
```

## API Rate Limits

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

Check your current rate limit:
```python
result = await registry.execute_tool("github", "rate_limit")
print(result["data"]["remaining"])
```

## Error Handling

All tools return standardized result dictionaries:

```python
{
    "success": True,      # or False on error
    "data": {...},        # Result data on success
    "error": "...",       # Error message on failure
    "status_code": 200    # HTTP status code
}
```

Common errors:
- `Bad credentials` - Invalid or expired token
- `Not Found` - Repository or resource doesn't exist
- `Validation Failed` - Missing or invalid parameters
- `rate limit exceeded` - API limit reached

## Documentation

- [SKILL.md](SKILL.md) - Complete tool documentation
- [OCLAWMA Skills Guide](https://github.com/openclaw/oclawma/blob/main/docs/SKILL_PACKAGING.md)

## License

MIT License - See [LICENSE](LICENSE) for details.

## Contributing

Contributions are welcome! Please see our [Contributing Guide](CONTRIBUTING.md) for details.

## Support

- Issues: [GitHub Issues](https://github.com/openclaw/oclawma-skill-github/issues)
- Discussions: [GitHub Discussions](https://github.com/openclaw/oclawma/discussions)
