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
    • Secrets = 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 3.5: Configure Bypass Rules (if branch protection is enabled)

If your organisation uses a branch ruleset that requires pull requests before merging into the default branch (e.g. main), EasyHosting's GitHub App must be granted bypass access so it can commit CI/CD configuration files directly to that branch.

How to check: Go to your organisation settings → Code security → Rulesets. If a ruleset targets the default branch and includes the "Require a pull request before merging" rule, you must follow the steps below.

Add the GitHub App to the bypass list

  1. Go to Organisation Settings → Code security → Rulesets.
  2. Click on the ruleset that protects your default branch (e.g. main or master).
  3. Under Bypass list, click + Add bypass.
  4. Select GitHub Apps as the actor type.
  5. Search for your app by the name you chose in Step 1 (e.g. EasyHosting App).
  6. Set the bypass mode to Always allow.
  7. Save the ruleset.

Why "Always allow"? EasyHosting pushes commits directly to the default branch when deploying services. The "Allow for pull requests only" mode is not sufficient — it only permits creating and merging PRs, not direct pushes.

Note: You need the App ID from Step 1 to identify your app if multiple apps are listed during the search.

Note: If your repository also has a classic Branch protection rule (not a ruleset) on the default branch, ensure the "Do not allow bypassing the above settings" checkbox is deselected. If it is enabled, it overrides all bypass lists and prevents EasyHosting from pushing directly to the branch.

💻 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.