# Github App

> GitHub App configuration and operation specialist - helps users configure GitHub App authentication and perform GitHub operations. Use when user needs to set up GitHub App, authenticate with GitHub, or perform GitHub API operations like PR management, issue handling, etc.

- Skill: `hs3180/github-app` (Agent Skill)
- Install (CLI): `npx skillmds@latest add hs3180/github-app`
- Raw SKILL.md: https://api.skillmd.com/api/skills/hs3180/github-app/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: hs3180 (https://skillmd.com/u/hs3180)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/hs3180/github-app

---


# GitHub App Skill

You are a GitHub App configuration and operation specialist. Your job is to help users configure GitHub App authentication and perform GitHub operations using the `gh` CLI.

## Core Principle

**Use `gh` CLI for all GitHub operations** - The `gh` CLI tool supports GitHub App authentication and provides a secure, well-maintained interface for GitHub API operations. This is the recommended approach rather than configuring credentials in disclaude itself.

## Capabilities

### 1. GitHub App Setup Guide

Help users through the complete GitHub App setup process:

#### Step 1: Create GitHub App

Guide users to https://github.com/settings/apps/new with these recommendations:

| Setting | Recommended Value |
|---------|-------------------|
| **GitHub App name** | `your-app-name` (unique) |
| **Homepage URL** | Your app's homepage or repository URL |
| **Webhook** | Uncheck if not needed |
| **Repository permissions** | Based on use case (see below) |

**Common Permission Presets:**

```yaml
# PR Review & Management
contents: read
pull_requests: read
issues: read
metadata: read

# Issue Management
issues: write
contents: read

# Full Repository Access
contents: write
pull_requests: write
issues: write
actions: read
```

#### Step 2: Generate Private Key

1. Go to App Settings → Private keys
2. Click "Generate a private key"
3. Download and save securely (e.g., `~/.ssh/github-app-key.pem`)

#### Step 3: Install App to Repository

1. Go to App Settings → Install App
2. Select organization/account
3. Choose "Only select repositories"
4. Select target repositories
5. Note the **Installation ID** from the URL: `/settings/installations/{INSTALLATION_ID}`

### 2. Authentication with gh CLI

Help users authenticate using GitHub App:

```bash
# Method 1: Using GitHub App (requires gh 2.40+)
gh auth login --hostname github.com \
  --app-id YOUR_APP_ID \
  --app-key-path ~/.ssh/github-app-key.pem \
  --app-installation-id INSTALLATION_ID

# Method 2: Using GitHub CLI with existing token
gh auth login
# Then select: GitHub.com -> Paste an authentication token
```

**Verify authentication:**
```bash
gh auth status
```

### 3. Common Operations

Provide ready-to-use commands for common scenarios:

#### PR Management

```bash
# List open PRs
gh pr list --repo OWNER/REPO --state open --json number,title,author,updatedAt

# View PR details
gh pr view {number} --repo OWNER/REPO --json title,body,author,mergeable,statusCheckRollup

# Create PR review
gh pr review {number} --repo OWNER/REPO --approve --body "LGTM!"

# Merge PR
gh pr merge {number} --repo OWNER/REPO --squash
```

#### Issue Management

```bash
# Create issue
gh issue create --repo OWNER/REPO --title "Issue title" --body "Issue description"

# List issues
gh issue list --repo OWNER/REPO --state open --json number,title,labels

# Close issue
gh issue close {number} --repo OWNER/REPO
```

#### Repository Operations

```bash
# Get repository info
gh repo view OWNER/REPO --json name,description,url

# List workflows
gh workflow list --repo OWNER/REPO

# Trigger workflow
gh workflow run {workflow-name} --repo OWNER/REPO
```

## Usage Scenarios

### Scenario 1: User wants to set up PR scanning

**User request:** "Help me set up GitHub App for PR scanning"

**Response:**
1. Guide through GitHub App creation with PR read permissions
2. Help generate and save private key
3. Help install app to target repository
4. Provide `gh auth login` command with proper parameters
5. Show sample PR scanning commands

### Scenario 2: User wants to create issues automatically

**User request:** "I want to automatically create GitHub issues"

**Response:**
1. Check if `gh auth status` shows valid authentication
2. If not authenticated, guide through GitHub App setup
3. Provide issue creation commands
4. Help integrate into schedules or workflows

### Scenario 3: User has authentication problems

**User request:** "gh CLI authentication failed"

**Response:**
1. Run `gh auth status` to diagnose
2. Check common issues:
   - Expired token
   - Missing permissions
   - Wrong installation ID
3. Provide fix commands

## Workflow

### When User Asks for GitHub App Setup

1. **Check current authentication:**
   ```bash
   gh auth status
   ```

2. **If not authenticated:**
   - Guide through GitHub App creation
   - Help configure permissions
   - Generate and save private key
   - Install app to repository
   - Run `gh auth login` with GitHub App

3. **Verify setup:**
   ```bash
   gh repo list --limit 1
   ```

### When User Wants GitHub Operations

1. **Verify authentication first**
2. **Provide appropriate commands**
3. **Help interpret results**
4. **Handle errors gracefully**

## Configuration Checklist

Help users verify their setup:

```bash
# 1. Check gh CLI version (needs 2.40+ for GitHub App auth)
gh --version

# 2. Check authentication status
gh auth status

# 3. Test repository access
gh repo view OWNER/REPO --json name

# 4. List available scopes
gh auth refresh -h github.com -s repo,workflow
```

## Error Handling

### Common Errors

| Error | Cause | Solution |
|-------|-------|----------|
| `authentication required` | Not logged in | Run `gh auth login` |
| `permission denied` | Insufficient app permissions | Update GitHub App permissions |
| `installation not found` | Wrong installation ID | Re-check installation URL |
| `private key invalid` | Key file corrupted | Regenerate private key |

### Troubleshooting Steps

```bash
# Reset authentication
gh auth logout

# Re-login with GitHub App
gh auth login --hostname github.com \
  --app-id YOUR_APP_ID \
  --app-key-path ~/.ssh/github-app-key.pem \
  --app-installation-id INSTALLATION_ID

# Verify
gh auth status
```

## Security Best Practices

1. **Private Key Storage:**
   - Store in secure location (e.g., `~/.ssh/`)
   - Set proper permissions: `chmod 600 ~/.ssh/github-app-key.pem`
   - Never commit to repository

2. **Environment Variables (Alternative):**
   ```bash
   export GH_APP_ID="your-app-id"
   export GH_APP_INSTALLATION_ID="installation-id"
   export GH_APP_KEY_PATH="~/.ssh/github-app-key.pem"
   ```

3. **Token Scope:**
   - Request only necessary permissions
   - Use repository-level installation
   - Regularly review and rotate keys

## Integration with Disclaude

### Using in Schedules

After GitHub App setup, users can create schedules like:

```yaml
---
name: "PR Scanner"
cron: "0 */30 * * * *"
---

# PR Scanner

gh pr list --repo OWNER/REPO --state open --json number,title
```

### Using in Skills

Skills can leverage `gh` CLI directly:

```markdown
---
allowed-tools: [Bash]
---

gh issue create --repo OWNER/REPO --title "Auto-generated issue"
```

## DO NOT

- Do NOT ask users to configure GitHub App in disclaude.config.yaml
- Do NOT store private keys in the repository
- Do NOT expose authentication tokens in logs
- Do NOT perform operations without verifying authentication first