Skip to main content
Safe Settings requires a GitHub App to authenticate and manage repository settings across your organization. This guide walks you through creating and configuring the app.

​
Creation Methods

There are two ways to create a GitHub App for Safe Settings:
  1. Manifest Flow (Recommended) - Automated setup using Probot
  2. Manual Creation - Manual configuration in GitHub settings
The easiest way to create the GitHub App is using the manifest flow, which automatically configures all required permissions.
1
Prepare the Source Code
2
Clone and set up the Safe Settings repository:
3
git clone https://github.com/github/safe-settings.git
cd safe-settings/
npm install
4
Configure Environment
5
Create .env file from the example:
6
cp .env.example .env
7
Set the organization variable:
8
# .env
GH_ORG=your-organization-name
9
If you’re installing the app in a personal account instead of an organization, leave GH_ORG empty.
10
Start the Application
11
Start Safe Settings locally:
12
npm run dev
13
The app will start on port 3000.
14
Create the App via Manifest
15
  • Open your browser to: http://localhost:3000/probot
  • Click the link to create a GitHub App
  • Follow the GitHub prompts to complete the creation
  • Download the private key when prompted
    • 16
    Update Environment
    17
    After creation, GitHub will provide:
    18
  • App ID
  • Webhook Secret
  • Private Key (downloaded file)
    • 19
    Update your .env file:
    20
    APP_ID=123456
WEBHOOK_SECRET=your-webhook-secret
PRIVATE_KEY="$(cat ~/Downloads/*.private-key.pem | base64)"
    21
    Install the App
    22
    Install the GitHub App in your organization:
    23
    You must install the app for all repositories in your organization for Safe Settings to work correctly.

    ​
    Method 2: Manual Creation

    If you prefer manual configuration or can’t use the manifest flow:
    2
    Go to your GitHub account or organization settings:
    3
  • Personal: https://github.com/settings/apps/new
  • Organization: https://github.com/organizations/YOUR-ORG/settings/apps/new
    • 4
    Configure Basic Information
    5
    Fill in the basic app details:
    6
    FieldValueGitHub App namesafe-settings (or your preferred name)Homepage URLhttps://github.com/github/safe-settingsWebhook URLYour deployment URL + /api/github/webhooksWebhook SecretGenerate with: openssl rand -base64 32
    7
    For the webhook URL, use your deployment endpoint. For AWS Lambda, this will be your Function URL. For Docker, it might be https://your-domain.com/api/github/webhooks.
    8
    Set Repository Permissions
    9
    Configure the following repository permissions:
    10
    PermissionAccess LevelActionsRead-onlyAdministrationRead & WriteChecksRead & WriteCommit statusesRead & WriteContentsRead & WriteCustom propertiesRead & WriteEnvironmentsRead & WriteIssuesRead & WriteMetadataRead-onlyPull requestsRead & WriteVariablesRead & Write
    11
    Set Organization Permissions
    12
    Configure the following organization permissions:
    13
    PermissionAccess LevelAdministrationRead & WriteCustom propertiesAdminMembersRead & Write
    14
    Subscribe to Events
    15
    Enable the following webhook events:
    16
  • Branch protection rule
  • Check run
  • Check suite
  • Create
  • Custom property values
  • Member
  • Pull request
  • Push
  • Repository
  • Repository ruleset
  • Team
    • 17
    Create the App
    18
    Click Create GitHub App to finalize the creation.
    19
    Generate Private Key
    20
    After creation:
    21
  • Scroll down to Private keys
  • Click Generate a private key
  • Save the downloaded .pem file securely
    • 22
    Install the App
    23
    Click the Install App button and select:
    24
  • All repositories (required)
  • Your organization or account

    • ​
    Permissions Reference

    Here’s the complete permissions configuration needed for Safe Settings:

    ​
    Repository Permissions

    Actions: Read-only
Administration: Read & Write
Checks: Read & Write
Commit statuses: Read & Write
Contents: Read & Write
Custom properties: Read & Write
Environments: Read & Write
Issues: Read & Write
Metadata: Read-only
Pull requests: Read & Write
Variables: Read & Write

    ​
    Organization Permissions

    Administration: Read & Write
Custom properties: Admin
Members: Read & Write

    ​
    Webhook Events

    - Branch protection rule
- Check run
- Check suite
- Create
- Custom property values
- Member
- Pull request
- Push
- Repository
- Repository ruleset
- Team

    ​
    Webhook Configuration

    The webhook URL format depends on your deployment method: 
    https://your-domain.com/api/github/webhooks
    For local development, use SMEE.io to proxy webhooks to your local machine.

    ​
    Testing the App

    After creating and installing the app:

    ​
    Verify Installation

    Check that the app is installed: 
    # View installed apps
gh api /orgs/YOUR-ORG/installations

    ​
    Test Webhook Delivery

    1. Go to your GitHub App settings
    2. Navigate to Advanced tab
    3. Check Recent Deliveries
    4. Verify webhooks are being received

    ​
    Create Test Repository

    Create a test repository to trigger the app: 
    gh repo create your-org/test-repo --private
    Check the Safe Settings logs to verify it processed the event.

    ​
    Environment Variables

    After creating the GitHub App, you’ll have these credentials: 
    # Required
APP_ID=123456
WEBHOOK_SECRET=your-generated-webhook-secret
PRIVATE_KEY="$(cat private-key.pem | base64)"

# Or use file path
PRIVATE_KEY_PATH=/path/to/private-key.pem
    Keep your private key and webhook secret secure. Never commit them to version control.

    ​
    Base64 Encoding Private Key

    For containerized deployments, encode the private key: 
    cat private-key.pem | base64

    ​
    Updating Webhook URL

    If you need to update the webhook URL after deployment:

    ​
    Via GitHub UI

    1. Go to GitHub App settings
    2. Update Webhook URL
    3. Save changes

    ​
    Via GitHub CLI

    gh api --method PATCH /app \
  -f webhook_url='https://new-url.com/api/github/webhooks'

    ​
    Troubleshooting

    ​
    Webhook Not Receiving Events

    • Verify webhook URL is correct and accessible
    • Check Recent Deliveries in app settings for errors
    • Ensure firewall allows GitHub webhook IPs
    • Verify WEBHOOK_SECRET matches in both GitHub and your deployment

    ​
    Authentication Errors

    • Verify APP_ID is correct
    • Ensure private key is properly formatted
    • Check that private key matches the app
    • Verify app is installed in the organization

    ​
    Permission Errors

    • Verify all required permissions are granted
    • Check that app is installed for all repositories
    • Ensure organization permissions are granted (not just repository)

    ​
    Next Steps

    With your GitHub App created, choose a deployment method:

    Docker

    Deploy with Docker containers

    AWS Lambda

    Deploy to AWS Lambda

    Kubernetes

    Deploy to Kubernetes

    GitHub Actions

    Run with GitHub Actions

    Build docs developers (and LLMs) love

    Get started for freeTalk to us