Skip to content

GitHub App Setup Documentation

This guide will walk you through the steps to create and configure a GitHub App for your integration needs.

📌 Prerequisites

  • A GitHub account with access to the organization or repositories where the app will be installed.
  • Admin permissions for the organization if the app is organization-wide.

🛠️ Step 1: Create the GitHub App

  1. Go to GitHub Developer Settings (replace {OrgName} with your actual organization name).
  2. Click on "New GitHub App".
  3. Fill in the required fields:
  4. GitHub App name: Choose a unique and descriptive name. (e.g., EasyHosting App)
  5. Homepage URL: (e.g., https://{SLUG}.easyhosting.strongminds.dev).
  6. User authorization callback URL: Leave blank.
  7. Under Webhook, uncheck the Active checkbox.
  8. Under Permissions, add
  9. Repository permissions
    • Actions = Read and write
    • Administration = Read and write
    • Contents = Read and write
    • Environments = Read and write
    • Workflows = Read and write
  10. Select Where can this GitHub App be installed?

  11. Only on this account

  12. Click Create GitHub App.

  13. Note down App Id (To be used in step 4)

🔐 Step 2: Generate App Credentials

After creation:

  1. Generate a private key:
  2. Click Generate a private key.
  3. Download and securely store the .pem file. (To be used in step 4)
  4. App ID and Client ID:
  5. You’ll find these on the app settings page.
  6. Client secret:
  7. Click Generate a new client secret.
  8. Store it securely.

🔧 Step 3: Install the App

  1. Go to your GitHub App settings.
  2. Click Install App.
  3. Choose to install on your user or organization account.
  4. Select the repositories to install it on, or grant access to all.
  5. Note down the installation id from the url https://github.com/organizations/{ORG}/settings/installations/{INSTALLATION_ID} (To be used in step 4)

💻 Step 4: Use the App in EasyHosting

  1. Navigate to your EasyHosting instance
  2. Goto Credentials
  3. Goto Code repository
  4. Add credential
  5. Add URL https://github.com/{ORG}
  6. Credential Type: Github App
  7. Insert the app id from the Github App
  8. Insert the installation id you noted down
  9. Insert the private key you generated in step 2
  10. Add repository credential

📝 Resources

🧹 Best Practices

  • Keep your private key secure and rotate it periodically.
  • Limit permissions to only what's necessary.