Setup Guide

This guide will help you configure your GitHub repository to use the AI-powered workflows documented in this site.

Prerequisites

Before setting up the workflows, ensure you have:

A GitHub repository where you want to deploy the workflows
Administrative access to the repository
A GitHub App for authentication (or ability to create one)
Access to Claude Code OAuth credentials

Step 1: Create a GitHub App

You'll need a GitHub App to authenticate the workflows with your repository.

1.1 Create the App

Go to GitHub Settings → Developer settings → GitHub Apps
Click "New GitHub App"
Fill in the basic information:
- App name: your-repo-ai-assistant (choose a unique name)
- Homepage URL: Your repository URL
- Webhook URL: Leave empty for now
- Webhook secret: Leave empty

1.2 Set Permissions

Configure the following Repository permissions:

Contents: Read
Issues: Write
Pull requests: Write
Metadata: Read

1.3 Subscribe to Events

Subscribe to these events:

Issues
Issue comments
Pull requests
Pull request reviews
Pull request review comments

1.4 Install the App

After creating the app:

Note down the App ID (you'll need this for secrets)
Generate and download a private key
Install the app on your target repository

Step 2: Configure Repository Secrets

Navigate to your repository Settings → Secrets and variables → Actions.

Required Secrets

Add the following secrets by clicking "New repository secret":

APP_ID

Value: The App ID from Step 1.4
Description: GitHub App ID for token generation

PRIVATE_KEY

Value: The entire contents of the private key file (.pem) from Step 1.4
Description: GitHub App private key for authentication
Format: Paste the entire key including headers:

-----BEGIN RSA PRIVATE KEY-----
[Your key content here]  
-----END RSA PRIVATE KEY-----

CLAUDE_CODE_OAUTH_TOKEN

Value: Your Claude Code OAuth token
Description: OAuth token for Claude Code integration
How to obtain:
1. Install Claude Code CLI
2. Run authentication setup
3. Extract the OAuth token from your credentials

Step 3: Configure Repository Variables

In the same Secrets and variables section, click the "Variables" tab.

Required Variables

ALLOWED_USER_LIST

Value: JSON array of GitHub usernames authorized to use the AI assistant
Format: ["username1", "username2", "admin"]
Example: ["john-doe", "jane-smith", "team-lead"]
Description: Only users in this list can trigger the AI on-demand workflow

Step 4: Add Workflow Files

Copy the workflow files to your repository's .github/workflows/ directory.

4.1 AI On-Demand Workflow

Create .github/workflows/ai-on-demand.yaml with the workflow configuration.

4.2 AI Code Review Workflow

Create .github/workflows/ai-review.yaml with the review workflow configuration.

Step 5: Test the Setup

5.1 Test AI On-Demand

Create a new issue or comment on an existing one
Include @efp-dev-ops (or your configured mention) in the comment
Add a request like: "Can you help me understand this repository structure?"
Verify that the workflow triggers and responds

5.2 Test AI Code Review

Create a pull request with some code changes
Verify that the AI Code Review workflow automatically triggers
Check that review comments are posted to the pull request

Troubleshooting

Common Issues

Workflow not triggering:

Verify workflow files are in .github/workflows/ directory
Check that secrets and variables are properly set
Ensure the user is in the ALLOWED_USER_LIST

Authentication errors:

Verify GitHub App credentials are correct
Check that the app is installed on the repository
Ensure proper permissions are set on the GitHub App

Claude Code connection issues:

Verify the OAuth token is valid
Check Claude Code service status
Ensure the token has proper scopes

Permission errors:

Verify repository permissions in GitHub App settings
Check that workflow has necessary permissions in YAML

Testing Tips

Start with a simple test request
Check the Actions tab for workflow execution logs
Verify environment variables in workflow runs
Test both workflows independently

Security Considerations

User Authorization: Only authorized users in ALLOWED_USER_LIST can trigger workflows
Token Scoping: GitHub App uses minimal required permissions
Input Validation: User input is validated and truncated
Secret Management: All sensitive credentials are stored as GitHub secrets

Customization Options

Change the Mention Trigger

To use a different mention (e.g., @my-bot):

Update the workflow conditions
Update the instruction extraction logic
Update your team documentation

Adjust Review Criteria

Modify the direct_prompt in the AI Code Review workflow to focus on specific aspects like:

Security-focused reviews
Performance analysis
Documentation standards
Framework-specific best practices