GitHub Integration - Autohand Docs

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):

# 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:

Go to Settings > Integrations > GitHub in your Autohand dashboard
Click Install GitHub App
Select the repositories you want to connect
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:

{
  "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:

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:

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:

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 "[email protected]"
          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:

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 "[email protected]"
          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

Go to your repository Settings > Secrets and variables > Actions
Click New repository secret
Add each required secret

Environment variables

These environment variables are automatically available in GitHub Actions:

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

- 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

- 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

- 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

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

- 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:

- 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