Skip to main content

​
Overview

The /install-gh-app command provides a guided workflow for installing the Factory GitHub App and configuring GitHub Actions workflows. This enables Droid to respond to @droid mentions in issues and PR comments, and optionally provide automated code reviews on new pull requests. When you run /install-gh-app, droid guides you through verifying prerequisites, selecting a repository, installing the GitHub App, and creating workflow files via a pull request.

​
Quick start

1

Start the installation flow

In an interactive droid session, type:
/install-gh-app
2

Pass preflight checks

Droid verifies that you have:
  • GitHub CLI (gh) installed
  • Authenticated with GitHub (gh auth login)
  • Required OAuth scopes (repo, read:org)
3

Select a repository

Choose from two options:
  • Use current repository - Auto-detected from your git remote
  • Enter a different repository - Type owner/repo or a GitHub URL
4

Install the GitHub App

Your browser opens to install the Factory Droid GitHub App. Grant access to the selected repository.
5

Select workflows

Choose which workflows to enable:
  • @Droid - Respond to @droid mentions in issues and PR comments
  • Droid Review - Automated code review on new PRs
6

Create the PR

Droid creates a branch with workflow files and opens a pull request for you to review and merge.

​
Prerequisites

Before running /install-gh-app, ensure you have the GitHub CLI installed and authenticated.

​
Install GitHub CLI

brew install gh

​
Authenticate with GitHub

gh auth login

​
Verify required scopes

The CLI needs repo and read:org scopes. If missing, refresh your authentication: 
gh auth refresh -s repo,read:org

​
Available workflows

​
@Droid workflow

Enables Droid to respond when you tag @droid in:
  • Issue comments
  • Pull request comments
  • Pull request reviews
  • Issue descriptions and titles
Triggers:
  • issue_comment - When a comment contains @droid
  • pull_request_review_comment - When a PR review comment contains @droid
  • pull_request_review - When a PR review body contains @droid
  • issues - When an issue body or title contains @droid
Use cases:
  • Ask Droid to implement features described in issues
  • Request code changes in PR comments
  • Get help understanding code in reviews

​
Droid Review workflow

Provides automated code review on new pull requests. Triggers:
  • pull_request - When a PR is opened, reopened, or marked ready for review
Use cases:
  • Automatic first-pass review on all PRs
  • Catch common issues before human review
  • Consistent review coverage across the team

​
Setup steps after installation

After the /install-gh-app workflow completes, you need to:
1

Review the pull request

A PR has been created in your repository with the workflow files. Review the changes.
2

Generate a Factory API key

Go to https://app.factory.ai/settings/api-keys and create a new API key.
3

Add the secret to GitHub

In your repository settings, go to Settings > Secrets and variables > Actions and add a new repository secret:
  • Name: FACTORY_API_KEY
  • Value: Your generated API key
4

Merge the PR

Once the secret is configured, merge the workflow PR to enable Droid.

​
Permissions

​
Repository admin permissions

For the smoothest setup, you should have admin access to the repository. If you don’t have admin permissions, you’ll see a warning but can still proceed. You may need a repository admin to:
  • Approve the GitHub App installation
  • Add the FACTORY_API_KEY secret
  • Merge the workflow PR

​
GitHub App permissions

The Factory Droid GitHub App requires these permissions:
  • Contents: Read and write (to push workflow files and make code changes)
  • Pull requests: Read and write (to create PRs and post reviews)
  • Issues: Read and write (to respond to issue comments)
  • Actions: Read (to monitor workflow runs)

​
Tips and best practices

  • Start with @Droid only if you want manual control over when Droid participates
  • Enable both for full automation with code review on every PR
  • Droid Review alone if you only want automated reviews without @droid mentions
ErrorSolution
GitHub CLI not installedInstall gh using the commands above
Not logged inRun gh auth login
Missing permissionsRun gh auth refresh -s repo,read:org
API access errorCheck your internet connection and run gh auth status
Run /install-gh-app separately for each repository you want to configure. The flow automatically detects the current repository from your git remote.

​
Example workflow

# Start droid in your repository
cd my-project
droid

# Run the installation command
> /install-gh-app

# Preflight checks pass automatically if gh is configured
# Select: Use current repository (my-org/my-project)
# Browser opens to install the GitHub App
# Select both workflows: @Droid and Droid Review
# PR is created with workflow files

# After the flow completes:
# 1. Add FACTORY_API_KEY secret to repository
# 2. Merge the PR
# 3. Tag @droid in an issue to test!

​
See also