How to register your own GitHub App

If you don't already have one, sign up for a GitHub account.

1. In the upper-right corner of any page on GitHub, click your profile photo.
2. Navigate to your account settings:
   • For an app owned by a personal account, click Settings.
   • For an app owned by an organization:
     • Click Your organizations.
     • To the right of the organization, click Settings.
3. In the left sidebar, click Developer settings.
4. In the left sidebar, click GitHub Apps.
5. Click New GitHub App.

1. Under GitHub App name, enter a name for your app. Choose a clear and short name (maximum 34 characters).
2. Optionally, under Description, type a description of your app. Users will see this when installing your app.
3. Under Homepage URL, type the full URL to your app's website. If you don't have a dedicated URL, you can use your GitHub repository URL or organization URL.

If your app needs to act on behalf of a user (generate a user access token):

1. Under Callback URL, enter https://api.tenklo.dev/oauth/callback.
2. You can add up to 10 callback URLs by clicking Add callback URL.

This field is required if you plan to select Request user authorization (OAuth) during installation in the next step, because that flow completes through the callback URL. It can be left blank otherwise.

1. By default, Expire user authorization tokens is selected. GitHub recommends keeping this option enabled.
2. If you want users to authorize your app when they install it, select Request user authorization (OAuth) during installation.
3. If you want to use device flow to generate a user access token, select Enable Device Flow.

What you do here depends on the previous step.

If you left Request user authorization (OAuth) during installation unselected, under Setup URL enter https://api.tenklo.dev/app-auth/connect. If you use a custom callback URL, take that URL and replace oauth/callback with app-auth/connect. Tenklo also shows the exact value on the integration page once you create it.

If you selected Request user authorization (OAuth) during installation, GitHub disables the Setup URL field. There is nothing to enter, the connection completes through the callback URL and the installation webhook instead. Keep going with this guide, the remaining steps apply to both flows.

In both cases, select Redirect on update under Post installation.

Leave webhooks off for now. The webhook URL and secret both come from your Tenklo integration, and that integration needs the App ID and private key you generate later in this guide.

1. Clear the Active checkbox. GitHub requires a webhook URL while Active is selected.
2. Under SSL verification, keep Enable SSL verification selected (recommended).

You turn webhooks on in the last step, once Tenklo can show you both values.

1. Under Permissions, choose the permissions your app needs. For each permission, select the dropdown menu and click Read-only, Read & write, or No access.
2. Select the minimum permissions necessary for your app's functionality.
3. Common permissions include:
   • Repository: Access to repositories
   • Issues: Access to issues
   • Pull requests: Access to pull requests
   • Workflows: Access to GitHub Actions workflows
   • Organization: Access to organization settings

Note: The permissions you select will determine what webhook events are available.

Under Where can this GitHub App be installed?, select:

• Only on this account - For apps that only you or your organization will use
• Any account - For apps that will be installed by other GitHub users or organizations

Click Create GitHub App to complete the registration process.

After creating your GitHub App:

1. On your GitHub App's settings page, scroll down to the Private keys section.
2. Click Generate a private key.
3. A private key file will be downloaded to your computer. Store this file securely as GitHub will not store a copy.
4. This private key will be needed when configuring your integration in Tenklo.

1. On your GitHub App's settings page, note the App ID at the top of the page.
2. Also note your App Public Link (e.g., https://github.com/apps/your-app-name).
3. You'll need both of these when configuring your integration in Tenklo.

Create the integration in Tenklo and fill in the App ID, App Private Key and App Public Link you just collected. Use GitHub (App) if you left user authorization during installation unselected, and GitHub (App OAuth) if you selected it.

GitHub (App OAuth) also needs the client ID and client secret. See GitHub App OAuth setup for those.

Saving these lets Tenklo derive the webhook secret, which it cannot do before the integration exists.

On your Tenklo integration page, copy the value under Webhook URL and the value under Webhook Secret. Then go back to your GitHub App settings:

1. Select the Active checkbox under Webhooks.

2. Under Webhook URL, paste the webhook URL from Tenklo.

3. Under Webhook secret, paste the webhook secret from Tenklo. This is required. GitHub only signs payloads when the secret is set, and Tenklo verifies every payload it receives. Keep it secure and never expose it publicly.

   

4. Under Subscribe to events, select the events you want your app to receive, such as Push, Pull request, Issues or Repository.

5. Save the changes.

Follow the Quickstart.