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 3.6: Enable deploy keys for your organisation

When you add a GitHub repository under Code repositories, EasyHosting provisions a write deploy key named easyhosting-deploy-key and stores its private key as the WRITE_DEPLOY_KEY repository secret. This also happens if adding a service creates the code repository for the first time. Adding another service to an existing code repository does not replace the key, and deleting the last service leaves the key in place.

The generated workflow uses this key to push the digest-pinned deployment manifest and release catalog record while honoring the repository's configured deploy-key bypass. If your organisation's deploy keys policy is disabled, provisioning fails with an error similar to:

Could not create deploy key in repository {repo}: Validation Failed (HTTP 422) [PublicKey custom Deploy keys are disabled for this repository]

Enable the policy

  1. Go to Organisation Settings → Policies → Deploy keys.
  2. Select Enabled.
  3. Click Save.

💻 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

The credential authorizes EasyHosting to access GitHub. Adding it does not create a deploy key; the key is created when the GitHub repository is added under Code repositories.

Repair a deploy key

If the deploy key or WRITE_DEPLOY_KEY secret is missing or no longer works:

  1. Check that the repository credential is valid and the GitHub App has the permissions described above. Correct any deploy-key policy or branch-rule issues first.
  2. Open Code repositories and select the affected repository.
  3. Open its More options dropdown and select Refresh deploy key. This action requires WRITE access in EasyHosting and is available for GitHub Git repositories.
  4. Wait for the success notification, then rerun the failed workflow if needed. Refreshing the key does not rerun a build or deployment.

Refresh creates a replacement key, updates WRITE_DEPLOY_KEY, and then removes the previous EasyHosting-managed key. Other deploy keys are left alone. If refresh fails, the error notification shows the problem; correct it and retry.

If adding a code repository reports that it was saved but its key could not be provisioned, open that repository's detail page and use the same refresh action. Existing repositories are not automatically rotated after an EasyHosting upgrade.

Deleting a code repository attempts to remove its managed key and secret. EasyHosting blocks deletion while a service uses the repository. Missing credentials or GitHub cleanup failures can leave these resources behind.

📝 Resources

🧹 Best Practices

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