Github App guidelines

https://github.com/github/github-app-js-sample/tree/main

Developer resources

Forward github events to platform

  smee -u https://smee.io/Oj0ZkULovroxbFC6 -t http://localhost:3500/api/webhook

Shared application should be linked via https://github.com/apps/<app name>/installations/new?state=AB12t

https://docs.github.com/en/apps/sharing-github-apps/sharing-your-github-app

Instructions to setup GitHub integration for local testing

Register a new GitHub App

Go to Settings/Developer settings/GitHub Apps

• Name: Any unique name. E.g. XX_huly_dev. Referred as GITHUB_APP later in the document.
• Homepage URL: http://localhost:8080
• Callback URL: http://localhost:8080/github
• Setup URL (optional): http://localhost:8080/github?op=installation
• Redirect on update: Checked

New webhook

Go to https://smee.io/ and click Start a new channel

• Use the provided Webhook Proxy URL as Webhook URL. Referred as WEBHOOK_URL later in the document.
• Webhook secret is: secret
• Keep Webhook Active checked.

Configure permissions for the app:

• Commit statuses: Read and write
• Contents: Read and write
• Custom properties: Read and write
• Discussions: Read and write
• Issues: Read and write
• Metadata: Read-only
• Pages: Read and write
• Projects: Read and write
• Pull requests: Read and write
• Webhooks: Read and write

Subscribe to events:

• Issues
• Pull request
• Pull request review
• Pull request review comment
• Pull request review thread

Final creation steps

• Create the app.
• Generate a new client secret. Referred as POD_GITHUB_CLIENT_SECRET later in the document.
• Create and download you private key file as well. Referred as POD_GITHUB_PRIVATE_KEY later in the document.
• You'll be provided with your GitHub app ID. Referred as POD_GITHUB_APPID later in the document.

Forward webhook events to local server

• Install smee client:

npm install --global smee-client

• To forward events (keep it up and running):

smee -u {WEBHOOK_URL} -t http://localhost:3500/api/webhook

Update local config files

.vscode/launch.json —> Debug Github integration

• "APP_ID": "{POD_GITHUB_APPID}" <— Numeric ID of the new application
• "CLIENT_ID": "{POD_GITHUB_CLIENTID}" <—- Client ID from the new application
• "CLIENT_SECRET": "{POD_GITHUB_CLIENT_SECRET}" <—- Client Secret from the new application
• "PRIVATE_KEY": "{POD_GITHUB_PRIVATE_KEY}" <—- PK from the new application

Note: PK value format: "-----BEGIN RSA PRIVATE KEY-----\n {ACTUAL_KEY_WO_LINE_BREAKS}\n-----END RSA PRIVATE KEY-----

dev/prod/public/config.json

• "GITHUB_APP": “{GITHUB_APP}" <— Textual name of the new application
• "GITHUB_CLIENTID": “{POD_GITHUB_CLIENTID}” <— Client ID from the new application

Usage

• Run dev GitHub pod (Debug Github integration) in vscode
• Run dev server
• On localhost:8080 Go to Settings -> Integrations -> Github
  • On the first tab authorise your GitHub
  • On the second tab of the dialog install the application, select a GH repo and connect to an existing/create a new connected repo in the tracker.
• Enjoy!

Note: If the application is already installed in GitHub, make any change e.g. switch between "All repositories" and "Only select repositories" and click "Save".