DEV Community

John Ajera
John Ajera

Posted on

How to Create a GitHub App for Atlantis

#github #apps #atlantis #terraform

How to Create a GitHub App for Atlantis

This article demonstrates how to create a GitHub App specifically for Atlantis, an automation tool for Terraform workflows. We'll cover the required fields, permissions, visibility settings, and how to generate the private key needed for Atlantis to authenticate and perform automated Terraform operations.

High-Level Steps

Creating a GitHub App involves:

  1. Navigate to App Creation Page - Access the GitHub App creation interface
  2. Fill Out Required Fields - Provide app name, URLs, and configuration
  3. Set Visibility - Choose public or private app
  4. Configure Permissions - Set minimum required permissions
  5. Create the App - Save the app configuration
  6. Generate Private Key - Download the authentication key

Prerequisites

  • GitHub account (personal or organization)
  • Access to organization settings (if creating for an organization)
  • Understanding of what the app will be used for (to determine permissions)

Use Case: Atlantis Terraform Automation

Atlantis is a self-hosted tool that automates Terraform workflows by:

  • Automated Terraform Planning - Running terraform plan on pull requests
  • Automated Terraform Applying - Running terraform apply when approved
  • Pull Request Integration - Commenting plan/apply results on PRs
  • State Management - Locking Terraform state during operations
  • Multi-Workspace Support - Managing multiple Terraform workspaces

This GitHub App allows Atlantis to authenticate with GitHub and interact with pull requests and repository content. This guide covers the manual creation step, which is a prerequisite before configuring Atlantis to use the app.

Step-by-Step Implementation

Step 1: Open the GitHub App Creation Page

Navigate to the GitHub App creation page based on your account type:

For Personal Account:

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

For Organization:

https://github.com/organizations/<ORG>/settings/apps/new
Enter fullscreen mode Exit fullscreen mode

Replace <ORG> with your GitHub organization name.

Key points:

  • Personal apps are created under your account settings
  • Organization apps require organization admin permissions
  • The URL structure differs between personal and organization accounts

Step 2: Fill Out Required Fields

Complete the required fields in the GitHub App creation form:

Basic Information

Field What to Enter Notes
GitHub App name atlantis or atlantis-app (or your preferred name) Must be unique across GitHub
Description This GitHub App is used by Atlantis to perform automated Terraform operations. It only interacts with pull requests and repository content as permitted. No personal account access or admin privileges are required. Recommended for clarity (Markdown supported)
Homepage URL Your organization's website or Atlantis documentation URL (e.g., https://www.runatlantis.io) Required field - can be a placeholder if not ready

Identifying and Authorizing Users

Field What to Enter Notes
Callback URL Leave blank Not required for Atlantis (only needed for OAuth flows)
Expire user authorization tokens Leave unchecked Not needed for Atlantis
Request user authorization (OAuth) during installation Leave unchecked Not required for Atlantis
Enable Device Flow Leave unchecked Not required for Atlantis

Note: For Atlantis, you don't need OAuth or user authorization flows. Atlantis uses the App's installation token for authentication.

Post Installation

Field What to Enter Notes
Setup URL Leave blank Optional - not required for Atlantis
Redirect on update Leave unchecked Not needed for Atlantis

Webhook Configuration

Field What to Enter Notes
Active Check this box Required - enables webhook event delivery
Webhook URL Your Atlantis webhook endpoint (e.g., https://atlantis.example.com/events) Required for Atlantis to receive GitHub events
Secret Generate a random string (e.g., using openssl rand -hex 32) Required for webhook payload verification - save this for Atlantis configuration

Configuration details for Atlantis:

  • GitHub App name: Use atlantis or a descriptive name like atlantis-terraform
  • Homepage URL: Your organization's website or link to Atlantis documentation
  • Callback URL: Not needed for Atlantis (leave blank)
  • Webhook URL: Your Atlantis server's webhook endpoint (e.g., https://atlantis.yourdomain.com/events)
  • Webhook secret: Generate a secure random string - you'll need to configure this in Atlantis as well

Best practices:

  • Use descriptive names that indicate the app is for Atlantis
  • Use HTTPS URLs for webhook endpoints (required by GitHub)
  • Generate webhook secret using: openssl rand -hex 32
  • Store webhook secret securely - you'll need it for Atlantis configuration

Step 3: Set Visibility and Installation Scope

Choose where the GitHub App can be installed:

Only on this account:

  • Only allow installation on your personal account or organization
  • Selected by default
  • Recommended for Atlantis - limits installation to your account/organization

Any account:

  • Allow installation by any user or organization
  • Not recommended for Atlantis unless you're building a public service

Recommendation for Atlantis:

Choose "Only on this account" since Atlantis is typically used for internal infrastructure automation and should only be installed on repositories within your organization that need Terraform automation.

Key points:

  • Installation scope can be changed later in app settings
  • "Only on this account" provides better security and control
  • "Any account" is only needed if you're distributing the app publicly

Step 4: Configure Atlantis Permissions

Atlantis requires specific permissions to function properly. Configure the following permissions:

Repository Permissions

Required Repository Permissions:

  • Contents: Read (to read Terraform files and repository content)
  • Pull requests: Write (to comment plan/apply results on PRs)
  • Metadata: Read (minimum required, always enabled)

Optional but Recommended:

  • Commit statuses: Write (to set commit status for Terraform operations)

Permission configuration:

  1. Expand "Repository permissions" section
  2. Find "Contents" and set to "Read" (Atlantis needs to read Terraform files)
  3. Find "Pull requests" and set to "Write" (Atlantis needs to comment on PRs)
  4. "Metadata" is automatically set to Read (minimum required)
  5. Optionally set "Commit statuses" to "Write" for commit status updates

Organization Permissions

  • Leave all organization permissions as "No access"
  • Atlantis doesn't need organization-level permissions

Account Permissions

  • Leave all account permissions as "No access"
  • Atlantis doesn't need user account access

Important notes for Atlantis:

  • These permissions allow Atlantis to read repository content and comment on pull requests
  • No admin privileges or personal account access is required
  • Permissions follow the principle of least privilege
  • You can update permissions later if needed

What each permission enables:

  • Contents (Read): Allows Atlantis to read Terraform files, state files, and repository content
  • Pull requests (Write): Allows Atlantis to post comments with plan/apply results on pull requests
  • Metadata (Read): Basic repository information (always required)
  • Commit statuses (Write): Allows Atlantis to set commit status (optional but useful)

Step 5: Subscribe to Events (Optional)

The "Subscribe to events" section allows you to receive additional webhook events. For Atlantis, you typically don't need to subscribe to additional events beyond what's automatically enabled by your permissions.

Available events:

  • Installation target: When a GitHub App installation target is renamed
  • Meta: When the App is deleted and the associated hook is removed
  • Security advisory: When security advisories are published, updated, or withdrawn

Recommendation for Atlantis:

  • Leave all event subscriptions unchecked
  • Atlantis receives the necessary events (pull requests, comments) automatically based on your permissions
  • Only subscribe to additional events if you have specific use cases

Step 6: Create the App

After filling out all required fields:

  1. Scroll down to the bottom of the form
  2. Review your configuration
  3. Click "Create GitHub App"

What happens:

  • GitHub validates your configuration
  • The app is created and assigned a unique App ID
  • You're redirected to the app's settings page
  • Client ID and Client Secret are generated automatically

After creation:

  • Note the App ID - you'll need this for authentication
  • Note the Client ID - used for OAuth flows
  • Save the Client Secret securely if you plan to use OAuth

Step 7: Generate a Private Key

The private key is required for authenticating as the GitHub App:

  1. On the app's settings page, scroll to "Private keys" section
  2. Click "Generate a private key"
  3. GitHub generates a .pem file
  4. Download the file immediately - you can only download it once

Important security notes:

  • The private key is only shown once - download it immediately
  • Store the .pem file securely (never commit to repositories)
  • Use environment variables or secret management tools
  • The key cannot be recovered if lost - you'll need to generate a new one

Key file details:

  • Format: PEM (Privacy-Enhanced Mail) format
  • Extension: .pem
  • Contains: RSA private key for JWT authentication
  • Usage: Used to generate JWT tokens for app authentication

Complete Example

Here's a summary of what you'll have after completing all steps:

App Information:

  • App ID: 123456 (example)
  • Client ID: Iv1.xxxxxxxxxxxxx (example)
  • Client Secret: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx (if using OAuth)
  • Private Key: app-name.2025-12-31.private-key.pem

Configuration for Atlantis:

  • App Name: atlantis
  • Description: This GitHub App is used by Atlantis to perform automated Terraform operations...
  • Homepage URL: https://www.runatlantis.io (or your organization URL)
  • Callback URL: (blank - not needed)
  • OAuth options: All unchecked (Expire tokens, Request OAuth, Device Flow)
  • Setup URL: (blank - not needed)
  • Redirect on update: Unchecked
  • Webhook Active: Checked
  • Webhook URL: https://atlantis.example.com/events
  • Webhook Secret: Generated and stored securely
  • Installation scope: Only on this account
  • Permissions:
    • Repository → Contents: Read
    • Repository → Pull requests: Read and write
    • Repository → Metadata: Read
    • Repository → Commit statuses: Write (optional)
    • Organization: No access
    • Account: No access
  • Event subscriptions: None (default events based on permissions)

Important Notes

App ID vs Client ID

  • App ID: Used for JWT authentication with the private key
  • Client ID: Used for OAuth flows (different authentication method)
  • Both are needed for different authentication scenarios

Private Key Security

  • Never commit the private key to version control
  • Store in secure secret management (GitHub Secrets, AWS Secrets Manager, etc.)
  • Use environment variables in CI/CD pipelines
  • Rotate keys periodically if compromised

Permission Management

  • Start with minimal permissions
  • Add permissions incrementally as needed
  • Review permissions regularly
  • Remove unused permissions

Webhook Configuration for Atlantis

  • Webhooks are required for Atlantis to receive GitHub events (pull requests, comments, etc.)
  • Webhook URL must point to your Atlantis server: https://atlantis.yourdomain.com/events
  • Webhook secret must match the secret configured in Atlantis
  • Test webhook delivery in app settings after Atlantis is running
  • Ensure your Atlantis server is publicly accessible (or use a tunnel for development)

Troubleshooting

App Creation Fails

Issue: Cannot create app - validation errors

  • Verify all required fields are filled
  • Check that app name is unique
  • Ensure URLs are valid (if provided)
  • Verify at least one permission is selected

Solution:

  • Review error messages in the form
  • Check for duplicate app names
  • Validate URL formats

Private Key Not Available

Issue: Cannot download private key after creation

  • Private keys can only be downloaded once
  • If you didn't download it, you need to generate a new one

Solution:

  1. Go to app settings → Private keys
  2. Click "Generate a new private key"
  3. Download immediately
  4. Revoke the old key if it was exposed

Permission Errors

Issue: App lacks required permissions

  • App needs additional permissions for operations
  • Some permissions require GitHub approval

Solution:

  1. Go to app settings → Permissions & events
  2. Add required permissions
  3. Save changes
  4. Reinstall the app on repositories (if already installed)

Webhook Delivery Failures

Issue: Webhooks not being received

  • Webhook URL not accessible
  • Webhook secret mismatch
  • SSL certificate issues

Solution:

  • Verify webhook URL is publicly accessible
  • Check webhook secret matches in both places
  • Ensure HTTPS is used (required by GitHub)
  • Test webhook delivery in app settings

Verification

After creating your GitHub App, verify you have:

  1. App ID - Visible in app settings
  2. Client ID - Visible in app settings
  3. Client Secret - Generated if using OAuth (save securely)
  4. Private Key - Downloaded .pem file (save securely)

Verify app creation:

  • App appears in your apps list: https://github.com/settings/apps
  • App settings page is accessible
  • Private key section shows key generation option

Test authentication:

# Verify private key format
openssl rsa -in app-name.private-key.pem -check -noout

# Should return: RSA key ok
Enter fullscreen mode Exit fullscreen mode

Next Steps: Configuring Atlantis

After creating your GitHub App, configure Atlantis to use it:

  1. Install the app on repositories or organizations that need Terraform automation
  2. Configure Atlantis with the App ID and private key:
    • Set ATLANTIS_GH_APP_ID environment variable
    • Set ATLANTIS_GH_APP_KEY to the private key file path
    • Set ATLANTIS_GH_WEBHOOK_SECRET to match the webhook secret
  3. Verify webhook delivery in GitHub App settings
  4. Test Atlantis by creating a pull request with Terraform changes

Atlantis configuration example:

# atlantis.yaml or environment variables
ATLANTIS_GH_APP_ID: "123456"
ATLANTIS_GH_APP_KEY: "/path/to/atlantis.private-key.pem"
ATLANTIS_GH_WEBHOOK_SECRET: "your-webhook-secret"
ATLANTIS_GH_HOSTNAME: "github.com"  # or "github.enterprise.com"
Enter fullscreen mode Exit fullscreen mode

For detailed Atlantis configuration, see the Atlantis documentation.

Conclusion

Creating a GitHub App for Atlantis is the first step in setting up automated Terraform workflows. By following this guide, you now have:

  • A configured GitHub App with Atlantis-specific permissions
  • App credentials (App ID, Client ID, Client Secret)
  • A private key for Atlantis authentication
  • Webhook configuration for receiving GitHub events
  • Understanding of app visibility and security settings

The app is now ready to be installed on repositories and configured in Atlantis. Atlantis will use this app to authenticate with GitHub and perform automated Terraform planning and applying on pull requests.

References

Top comments (0)