---
title: "GitHub Integration"
source: https://docs.autohand.ai/integrations/github
---

# GitHub

Integrate Autohand CLI with GitHub for automated code reviews, PR management, and CI/CD workflows using GitHub Actions.

## Overview

Autohand integrates with GitHub to provide:

-   Automated code reviews on pull requests
-   Issue triage and labeling
-   CI/CD pipeline automation with GitHub Actions
-   Automated bug fixes and refactoring
-   Documentation generation

## Authentication

Configure GitHub authentication in your Autohand settings:

### Personal Access Token

For personal repositories or small teams, use a GitHub Personal Access Token (PAT):

``` bash
# Set your GitHub token
export GITHUB_TOKEN="ghp_xxxxxxxxxxxxxxxxxxxx"

# Or configure in settings.json
autohand config set github.token "ghp_xxxxxxxxxxxxxxxxxxxx"
```

### GitHub App

For organizations, install the Autohand GitHub App for enhanced security and permissions:

1.  Go to **Settings > Integrations > GitHub** in your Autohand dashboard
2.  Click **Install GitHub App**
3.  Select the repositories you want to connect
4.  Authorize the required permissions

### Required permissions

| Permission | Access | Purpose |
|---|---|---|
| Contents | Read & Write | Read code and push changes |
| Pull requests | Read & Write | Create and review PRs |
| Issues | Read & Write | Manage issues |
| Workflows | Read & Write | Trigger and manage Actions |
| Checks | Read & Write | Report check results |
| Metadata | Read | Access repository metadata |

## CLI configuration

Configure GitHub integration in your `~/.autohand/settings.json`:

``` json
{
  "github": {
    "enabled": true,
    "token": "${GITHUB_TOKEN}",
    "defaultBranch": "main",
    "autoCreatePR": true,
    "prTemplate": ".github/PULL_REQUEST_TEMPLATE.md",
    "reviewers": ["@team/reviewers"],
    "labels": {
      "autohand": true,
      "automated": true
    },
    "signCommits": true,
    "commitMessageFormat": "conventional"
  }
}
```

### Configuration options

| Option | Description | Default |
|---|---|---|
| enabled | Enable GitHub integration | true |
| token | GitHub token or environment variable reference | - |
| defaultBranch | Default branch for PRs | main |
| autoCreatePR | Automatically create PRs for changes | false |
| prTemplate | Path to PR template file | - |
| reviewers | Default reviewers for PRs | [] |
| labels | Labels to add to PRs and issues | {} |
| signCommits | Sign commits with GPG | false |
| commitMessageFormat | Commit message format (conventional, angular, custom) | conventional |

## GitHub Actions

Run Autohand CLI in your CI/CD pipelines using GitHub Actions. This enables automated code reviews, fixes, and maintenance tasks.

### Basic workflow

Create `.github/workflows/autohand.yml`:

``` yaml
name: Autohand CI

on:
  pull_request:
    types: [opened, synchronize]
  issues:
    types: [opened, labeled]
  workflow_dispatch:
    inputs:
      task:
        description: 'Task to run'
        required: true
        type: string

jobs:
  autohand:
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write
      issues: write

    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install Autohand CLI
        run: npm install -g autohand

      - name: Run Autohand
        env:
          AUTOHAND_API_KEY: ${{ secrets.AUTOHAND_API_KEY }}
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          autohand --prompt "${{ github.event.inputs.task || 'Review this PR' }}" \
            --yes \
            --output json > result.json

      - name: Post results
        if: github.event_name == 'pull_request'
        uses: actions/github-script@v7
        with:
          script: |
            const fs = require('fs');
            const result = JSON.parse(fs.readFileSync('result.json', 'utf8'));
            await github.rest.issues.createComment({
              owner: context.repo.owner,
              repo: context.repo.repo,
              issue_number: context.issue.number,
              body: result.summary
            });
```

### Code review workflow

Automatically review pull requests:

``` yaml
name: Autohand Code Review

on:
  pull_request:
    types: [opened, synchronize, ready_for_review]

jobs:
  review:
    runs-on: ubuntu-latest
    if: github.event.pull_request.draft == false
    permissions:
      contents: read
      pull-requests: write

    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Install Autohand
        run: npm install -g autohand

      - name: Get changed files
        id: changed
        run: |
          echo "files=$(git diff --name-only origin/${{ github.base_ref }}...HEAD | tr '\n' ' ')" >> $GITHUB_OUTPUT

      - name: Review changes
        env:
          AUTOHAND_API_KEY: ${{ secrets.AUTOHAND_API_KEY }}
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          autohand --prompt "Review these changes for bugs, security issues, and best practices: ${{ steps.changed.outputs.files }}" \
            --restricted \
            --output markdown > review.md

      - name: Post review
        uses: actions/github-script@v7
        with:
          script: |
            const fs = require('fs');
            const review = fs.readFileSync('review.md', 'utf8');
            await github.rest.pulls.createReview({
              owner: context.repo.owner,
              repo: context.repo.repo,
              pull_number: context.issue.number,
              body: review,
              event: 'COMMENT'
            });
```

### Auto-fix workflow

Automatically fix issues when labeled:

``` yaml
name: Autohand Auto-Fix

on:
  issues:
    types: [labeled]

jobs:
  fix:
    runs-on: ubuntu-latest
    if: github.event.label.name == 'autohand-fix'
    permissions:
      contents: write
      pull-requests: write
      issues: write

    steps:
      - uses: actions/checkout@v4

      - name: Install Autohand
        run: npm install -g autohand

      - name: Create fix branch
        run: |
          git checkout -b autohand/fix-${{ github.event.issue.number }}

      - name: Apply fix
        env:
          AUTOHAND_API_KEY: ${{ secrets.AUTOHAND_API_KEY }}
        run: |
          autohand --prompt "Fix this issue: ${{ github.event.issue.title }} - ${{ github.event.issue.body }}" \
            --yes

      - name: Commit and push
        run: |
          git config user.name "Autohand Bot"
          git config user.email "bot@autohand.ai"
          git add -A
          git commit -m "fix: resolve #${{ github.event.issue.number }}" || exit 0
          git push origin autohand/fix-${{ github.event.issue.number }}

      - name: Create PR
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          gh pr create \
            --title "fix: resolve #${{ github.event.issue.number }}" \
            --body "Automated fix for #${{ github.event.issue.number }}" \
            --base main \
            --head autohand/fix-${{ github.event.issue.number }}
```

### Scheduled maintenance

Run maintenance tasks on a schedule:

``` yaml
name: Autohand Maintenance

on:
  schedule:
    - cron: '0 2 * * 1'  # Every Monday at 2 AM
  workflow_dispatch:

jobs:
  maintenance:
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write

    steps:
      - uses: actions/checkout@v4

      - name: Install Autohand
        run: npm install -g autohand

      - name: Run maintenance tasks
        env:
          AUTOHAND_API_KEY: ${{ secrets.AUTOHAND_API_KEY }}
        run: |
          autohand --prompt "Update dependencies and fix any deprecation warnings" --yes
          autohand --prompt "Remove unused imports and dead code" --yes
          autohand --prompt "Update documentation for any recent changes" --yes

      - name: Create maintenance PR
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          git config user.name "Autohand Bot"
          git config user.email "bot@autohand.ai"
          BRANCH="autohand/maintenance-$(date +%Y%m%d)"
          git checkout -b $BRANCH
          git add -A
          git commit -m "chore: automated maintenance" || exit 0
          git push origin $BRANCH
          gh pr create \
            --title "chore: weekly maintenance" \
            --body "Automated maintenance tasks by Autohand" \
            --base main \
            --head $BRANCH
```

## Secrets and environment

Configure the following secrets in your GitHub repository:

| Secret | Description | Required |
|---|---|---|
| AUTOHAND_API_KEY | Your Autohand API key | Yes |
| AUTOHAND_SECRET | Enterprise secret for organization features | No |
| OPENROUTER_API_KEY | OpenRouter API key (if using custom models) | No |

### Adding secrets

1.  Go to your repository **Settings > Secrets and variables > Actions**
2.  Click **New repository secret**
3.  Add each required secret

### Environment variables

These environment variables are automatically available in GitHub Actions:

``` yaml
env:
  AUTOHAND_API_KEY: ${{ secrets.AUTOHAND_API_KEY }}
  GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
  AUTOHAND_CI: "true"
  AUTOHAND_REPO: ${{ github.repository }}
  AUTOHAND_BRANCH: ${{ github.head_ref || github.ref_name }}
  AUTOHAND_PR_NUMBER: ${{ github.event.pull_request.number }}
  AUTOHAND_COMMIT_SHA: ${{ github.sha }}
```

## Pull request automation

Autohand can automate various PR tasks:

### Auto-labeling

``` yaml
- name: Auto-label PR
  env:
    AUTOHAND_API_KEY: ${{ secrets.AUTOHAND_API_KEY }}
  run: |
    LABELS=$(autohand --prompt "Suggest labels for this PR based on the changes" --output json | jq -r '.labels[]')
    gh pr edit ${{ github.event.pull_request.number }} --add-label "$LABELS"
```

### Auto-assign reviewers

``` yaml
- name: Assign reviewers
  env:
    AUTOHAND_API_KEY: ${{ secrets.AUTOHAND_API_KEY }}
  run: |
    REVIEWERS=$(autohand --prompt "Suggest reviewers based on code ownership" --output json | jq -r '.reviewers[]')
    gh pr edit ${{ github.event.pull_request.number }} --add-reviewer "$REVIEWERS"
```

### PR description generation

``` yaml
- name: Generate PR description
  env:
    AUTOHAND_API_KEY: ${{ secrets.AUTOHAND_API_KEY }}
  run: |
    DESCRIPTION=$(autohand --prompt "Generate a detailed PR description based on the changes" --output markdown)
    gh pr edit ${{ github.event.pull_request.number }} --body "$DESCRIPTION"
```

## Issue automation

Automate issue management with Autohand:

### Issue triage

``` yaml
name: Issue Triage

on:
  issues:
    types: [opened]

jobs:
  triage:
    runs-on: ubuntu-latest
    permissions:
      issues: write

    steps:
      - uses: actions/checkout@v4

      - name: Install Autohand
        run: npm install -g autohand

      - name: Analyze issue
        env:
          AUTOHAND_API_KEY: ${{ secrets.AUTOHAND_API_KEY }}
        run: |
          autohand --prompt "Analyze this issue and suggest labels, priority, and assignee: ${{ github.event.issue.title }} - ${{ github.event.issue.body }}" \
            --output json > triage.json

      - name: Apply triage
        uses: actions/github-script@v7
        with:
          script: |
            const fs = require('fs');
            const triage = JSON.parse(fs.readFileSync('triage.json', 'utf8'));

            await github.rest.issues.addLabels({
              owner: context.repo.owner,
              repo: context.repo.repo,
              issue_number: context.issue.number,
              labels: triage.labels
            });

            if (triage.comment) {
              await github.rest.issues.createComment({
                owner: context.repo.owner,
                repo: context.repo.repo,
                issue_number: context.issue.number,
                body: triage.comment
              });
            }
```

## Best practices

-   **Use restricted mode in CI**: Always use `--restricted` flag for automated reviews to prevent unintended changes.
-   **Set timeouts**: Configure appropriate timeouts for Autohand operations in your workflows.
-   **Review before merge**: Even with automation, have humans review critical changes.
-   **Use branch protection**: Enable branch protection rules to require checks before merging.
-   **Monitor usage**: Track API usage to avoid hitting rate limits.
-   **Cache dependencies**: Use GitHub Actions cache to speed up Autohand installation.

### Caching example

``` yaml
- name: Cache Autohand
  uses: actions/cache@v4
  with:
    path: ~/.npm
    key: ${{ runner.os }}-autohand-${{ hashFiles('**/package-lock.json') }}

- name: Install Autohand
  run: npm install -g autohand
```

## Troubleshooting

### Common issues

| Issue | Solution |
|---|---|
| Authentication failed | Verify AUTOHAND_API_KEY secret is set correctly |
| Permission denied | Check workflow permissions and GitHub App permissions |
| Rate limited | Add delays between operations or upgrade your plan |
| Workflow timeout | Increase timeout or break task into smaller steps |
| Changes not committed | Ensure contents: write permission is set |

### Debug mode

Enable debug logging in your workflow:

``` yaml
- name: Run Autohand (debug)
  env:
    AUTOHAND_API_KEY: ${{ secrets.AUTOHAND_API_KEY }}
    AUTOHAND_DEBUG: "true"
    AUTOHAND_LOG_LEVEL: "debug"
  run: autohand --prompt "Your task" --verbose
```