GitHub App Integration | Autonoma Documentation

Enable your Autonoma AI agents to create pull requests automatically when they reach ASSISTED or AUTONOMOUS modes in the ACMF.

Agents with PR Creation

The following agents can create pull requests directly when configured with GitHub App credentials:

coder-ai

Code generation

architect-ai

Architecture design

debug-ai

Bug fixes

security-ai

Security patches

review-ai

Code improvements

tester-ai

Test generation

maintain-ai

Maintenance updates

optimize-ai

Performance fixes

How It Works

When your agents progress through the ACMF maturity levels, they gain the ability to make code changes:

ACMF Mode	PR Behavior
OBSERVE	Agent logs proposed changes but takes no action
LEARNING	Agent submits PR requests for human approval before creation
ASSISTED	Agent creates PRs automatically; significant changes require approval
AUTONOMOUS	Agent creates and manages PRs independently

Prerequisites

An Autonoma account with agents deployed
Admin access to your GitHub organization or repository
AWS account with Secrets Manager and IAM access
AWS CLI installed and configured

1Generate Webhook Secret

The webhook secret is used to verify that incoming webhooks are genuinely from GitHub. Open a terminal and run:

openssl rand -hex 32

Example output: a1b2c3d4e5f6789012345678901234567890abcdef1234567890abcdef123456

Important: Save this value securely. You'll need it in Steps 4 and 7.

2Create GitHub App

For Organizations

Navigate to your organization's settings:

https://github.com/organizations/YOUR-ORG/settings/apps/new

For Personal Accounts

Navigate to your personal settings:

https://github.com/settings/apps/new

Fill in Basic Information

Field	Value
GitHub App name	`Your-Company Autonoma Agent Integration`
Description	Autonoma AI agents use this app to create pull requests with code improvements, bug fixes, and feature implementations.
Homepage URL	`https://www.theautonoma.io`

3Configure App Permissions

Set only these three Repository Permissions:

Permission	Access Level	Purpose
Contents	Read & write	Create branches and commits
Pull requests	Read & write	Create and manage PRs
Metadata	Read-only	Required (auto-selected)

Security Note: Do not grant additional permissions. Agents only need access to create PRs. Leave Organization and Account permissions at "No access".

4Configure Webhooks

Setting	Value
Webhook URL	`https://www.theautonoma.io/api/webhooks/github`
Webhook secret	Paste the secret from Step 1
SSL verification	Enable

Subscribe to Events

Pull request

Push

Workflow job

Workflow run

5Install the App

Click Install App in the left sidebar
Select your organization or account
Choose Only select repositories (recommended)
Select the repositories you want agents to access
Click Install

After installation, note the Installation ID from the URL:

https://github.com/settings/installations/12345678

The number at the end is your Installation ID

6Download Private Key

Go to your GitHub App settings
Scroll to Private keys section
Click Generate a private key
A .pem file will download automatically

Security: Store this file securely. Never commit it to version control.

7Store Credentials in AWS Secrets Manager

Store your GitHub App credentials securely in AWS Secrets Manager:

CRITICAL: Field names MUST use PascalCase (AppID, InstallationID, etc.). Using snake_case (app_id) will cause authentication failures.

# Set your values
export CUSTOMER_ID="your-customer-id"
export APP_ID="your-app-id"           # Numeric ID from GitHub App settings
export INSTALLATION_ID="your-installation-id"  # Numeric ID from URL
export WEBHOOK_SECRET="your-webhook-secret-from-step-1"
export PRIVATE_KEY_FILE="path/to/your-private-key.pem"

# Read private key (preserve PEM format)
PRIVATE_KEY=$(cat "$PRIVATE_KEY_FILE")

# Create the secret with PascalCase field names
aws secretsmanager create-secret \
  --name "autonoma/integrations/${CUSTOMER_ID}/github" \
  --description "GitHub App credentials for Autonoma AI agents" \
  --secret-string "$(cat <<EOF
{
  "AppID": ${APP_ID},
  "InstallationID": ${INSTALLATION_ID},
  "PrivateKeyPEM": $(echo "$PRIVATE_KEY" | jq -Rs .),
  "WebhookSecret": "${WEBHOOK_SECRET}"
}
EOF
)"

Required Fields (PascalCase)

Field	Type	Description
AppID	Integer	Numeric GitHub App ID from settings
InstallationID	Integer	Numeric Installation ID from URL
PrivateKeyPEM	String	Full PEM key including headers
WebhookSecret	String	Webhook secret from Step 1

8Create IAM Role for Agents

Create an IAM role that your agents will assume:

# Create trust policy
cat > /tmp/trust-policy.json << 'EOF'
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Service": "ecs-tasks.amazonaws.com"
      },
      "Action": "sts:AssumeRole"
    }
  ]
}
EOF

# Create the role
aws iam create-role \
  --role-name autonoma-agent-role \
  --assume-role-policy-document file:///tmp/trust-policy.json \
  --description "IAM role for Autonoma AI agents"

9Configure Integration in Autonoma

curl -X POST 'https://www.theautonoma.io/api/v1/integrations/github' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR-API-KEY' \
  -d '{
    "integration_name": "my-repo-integration",
    "github_repo": "your-org/your-repo",
    "github_installation_id": YOUR_INSTALLATION_ID,
    "secrets_manager_arn": "arn:aws:secretsmanager:...",
    "config": {
      "agents": [
        "coder-ai",
        "architect-ai",
        "debug-ai",
        "security-ai",
        "review-ai",
        "tester-ai",
        "maintain-ai",
        "optimize-ai"
      ],
      "require_review": true
    }
  }'

10Verify the Integration

Check webhook delivery

Go to your GitHub App settings → Advanced → Recent Deliveries. You should see a successful ping delivery.

Test agent PR creation

Trigger an agent workflow and check for PR requests in your Autonoma dashboard.

PR Creation Flow

Agent detects code change opportunity

Check ACMF Mode

OBSERVE

Log only

LEARNING/ASSISTED

Await Approval

Create PR

AUTONOMOUS

Create PR directly

CI/CD Runs → Webhook Events → Agent Learns

Troubleshooting

AppID=0 or InstallationID=0 in logs

Cause: Your AWS secret uses snake_case field names instead of PascalCase.

Fix: Verify your secret field names with:

aws secretsmanager get-secret-value --secret-id "your-secret" --query 'SecretString' --output text | jq 'keys'

Expected: ["AppID", "InstallationID", "PrivateKeyPEM", "WebhookSecret"]

Wrong: ["app_id", "installation_id", "private_key", "webhook_secret"]

Webhook delivery failures

Check GitHub App settings → Advanced → Recent Deliveries. Common issues:401/403: Webhook secret mismatch - regenerate and update

PR creation failures

Check your Autonoma dashboard for error details. Common issues: invalid private key, missing permissions, branch protection rules.

Need Help?

Our team is here to help you set up GitHub integration for your agents.

Contact Support Learn About ACMF