Skip to content

Create The GitHub App

Overview

Create a GitHub App for the self-hosted Code Review deployment. The app can be installed on either a GitHub organization or a personal GitHub account. It lets CloudAEye receive pull request webhooks, read repository content for indexing and review, write review output back to pull requests, and update check results.

See GitHub's Registering a GitHub App guide for reference.

Prerequisites

  • For an organization installation, access to create a GitHub App and permission to install it in the target organization. An organization owner may need to approve the installation.
  • For a personal-account installation, access to create and install a GitHub App in the target personal account.

Register the app under the account that will own and manage it:

  • Organization-owned app: Open the target organization's Settings, then select Developer settings > GitHub Apps > New GitHub App.
  • User-owned app: Open your personal Settings, then select Developer settings > GitHub Apps > New GitHub App.

Step 1: Fill In General Settings

Use values like the following:

GitHub App setting Value
GitHub App name A unique name such as cloudaeye-code-review-<company>
Description CloudAEye self-hosted code review integration

Step 2: Configure Webhooks

Keep webhooks active and set the webhook endpoint:

GitHub App setting Value
Active Enabled
Webhook secret Generate a long random secret and save it for terraform.tfvars

If the final ALB is not available yet, create the GitHub App, complete the Terraform deployment, get the final value from terraform output app_base_url, then update the GitHub App Webhook URL before testing pull request reviews.

Subscribe to these webhook events in the GitHub App:

Event GitHub event description
Check run Check run is created, requested, rerequested, or completed
Check suite Check suite is requested, rerequested, or completed
Commit comment Commit or diff commented on
Issue comment Issue comment created, edited, or deleted
Issues Issue opened, edited, deleted, closed, reopened, or assigned
Pull request Pull request opened, reopened, synchronized, or ready for review
Pull request review Pull request review submitted, edited, or dismissed
Pull request review comment Pull request diff comment created, edited, or deleted
Pull request review thread Pull request review thread resolved or unresolved

Step 3: Set Repository Permissions

Set the minimum permissions needed for Code Review:

Permission Access Why CloudAEye needs it
Checks Read and write Create or update review checks
Commit statuses Read Read commit status context
Contents Read-only Read source files for indexing and review
Issues Read and write Read and write issue-style pull request comments where GitHub uses issue APIs
Metadata Read-only Required by GitHub for GitHub Apps
Pull requests Read and write Read pull request diffs and write review output

Step 4: Choose Where The App Can Be Installed

Choose the installation scope based on where the repositories are owned:

Repository owner App owner Installation setting
Organization Same organization Select Only on this account.
Personal account Same personal account Select Only on this account.
Organization or personal account different from the app owner Another account you control Select Any account.

Only on this account supports both organization-owned and user-owned repositories when the app is registered under that same account. Use Any account only when the app must be installed outside the account that owns the app.

Step 5: Generate App Credentials

After the app is created:

  1. On the GitHub App settings page, copy the App ID.
  2. Copy the Client ID.
  3. Generate a Client secret and copy it immediately.
  4. Under Private keys, click Generate a private key.
  5. Download the .pem private key and store it securely.

GitHub downloads the private key once; keep the PEM file secure and do not commit it to source control.

Step 6: Install The GitHub App

Install the app on the organization or personal account that owns the repositories CloudAEye should review:

  1. In the GitHub App settings page, click Install App.
  2. Click Install next to the target organization or personal account.
  3. Select All repositories, or select Only select repositories and choose every repository that CloudAEye should review.
  4. Click Install.

The same GitHub App can have separate installations for a personal account and one or more organizations. Each installation has its own installation ID and repository access. Configure this self-hosted deployment with the installation that owns the repositories it will review.

After installation, record the installation ID from the browser URL while viewing the installation. The URL depends on the account type:

# Organization installation
https://github.com/organizations/<org>/settings/installations/<installation-id>

# Personal-account installation
https://github.com/settings/installations/<installation-id>