The following guide explains:

How to set up a Github app & configure it
Connect Github with Apideck
Subscribe to Github webhooks

Create a Github app & connect via Apideck

Log in to Github

After you have logged in to Github, let's get started by adding a Github App.

Navigate to https://github.com/settings/organizations to view your organizations.

Select the appropriate organisation for which you want to create a Github App, by clicking the "Settings" button.

This will bring you to the organisation settings page, at the bottom in the de side menu, the "Developers settings".

Register new Github app

Click on the "Github Apps" to go to the overview of all Github apps.

You can create a new Github app by clicking on the "New Github app" button.

This will take you to a large form where you can enter all the required information about your app, in different sections:

Setup App

App Name: Enter a meaningful name (for example, 'Apideck integration'), since when your users link their Github account, they will see the “App Name” is requesting to integrate.
Description: Provide a short description that will be presented to your users.
Homepage URL: The homepage of your company’s website or the url your SaaS product.

Configure authorization

Callback URL: The URL where the user will be redirected after granting your app access to their Github account. This should be

https://unify.apideck.com/vault/callback

Configure permissions

The next step is to configure the access permissions.

For the "repository permissions", you would typically request

Issues -
```
read and write
```
Issues and related comments, assignees, labels, and milestones.
Metadata -
```
read-only
```
Search repositories, list collaborators, and access repository metadata
Projects -
```
read-only
```
Manage classic projects within a repository.

For the "organization" we suggest setting the following permissions:

Members -
```
read-only
```
Organization members and teams.

Review the other settings of the app creation form and set them as suited for your application.

Once you are ready, click on "Create Github app" button at the bottom of the form to create the Github App.

ℹ️note: In case you want to register Github webhook events, follow the steps as described in the "Github Webhook Registration" guide.

Authentication details & app settings

Once your app is created, you can generate the Client credentials.

The Client ID is automatically generated when the app is created. For enabling the app, you need to generate a Client Secret.

Click on the "Generate new secret" button to generate a new Client Secret.

💡 TIP: Copy the "Client ID" and the "Client secret". You will need them in the next step.

Vault Connection Setup

Now that you have your Github App created and the needed credentials, you can enable the integration to connect to Github securely.

Goto the Apideck > Configuration > Issue Tracking > Github

Enter the OAuth client ID & Secret from Github.

Press "Save settings" to configure the Github integration.

You can test the connection by clicking "Test Vault", which will check if the connection is working.

🚀Now you are ready and clients can authorize the connection to their Github account in a secure way.

Do your first Github API call via the Issue Tracking API

Connect your Github account through Vault with a test session.
To test the access token, make a query to get your
```
Collections
```
endpoint using the Issue Tracking API.

curl \
  --request GET \
  --url 'https://unify.apideck.com/issue-tracking/collections' \
  --header 'Authorization: Bearer {APIDECK_API_KEY}' \
  --header 'x-apideck-app-id: {APIDECK_APP_ID}' \
  --header 'x-apideck-consumer-id: test-consumer' \
  --header 'x-apideck-service-id: github'

Github Webhook Registration

Register a Github webhook in Unify

Goto the Apideck > Configuration > Issue Tracking > Github On the Unify Github connector settings, at the bottom, you can find the “Webhook Execute URL”

💡 IMPORTANT: Copy the full “Webhook execute URL” since you need this URL to register it in Github.

Create a webhook subscription in Github

To register a webhook for your Github app,

Sign in to your Github account and go to the organisation settings page, and navigate to the "Github Apps" at the bottom in the "Developers settings" within the side menu.
Select the Github app for which you want to enable webhooks by clicking the "Edit" button.

Scroll down on the App configuration to the "Webhook" section

In the "Webhook URL" field, enter the “Webhook execute URL” from Unify (see above steps).

Click on the "Save Changes" button to register the webhook.
Configure the events you want to receive, by going to "Permissions" and checking the events. We suggest the events:
```
issues
```
,
```
label
```
,
```
issue comment
```

After the webhook URL has been registered, all Github events will be sent to Apideck for processing. In the next step, we will explain how you can subscribe to these Github events through Unify events.

After you have completed the above steps, you can subscribe your application to Unify Events.

The following guide will explain all the steps to subscribe to Unify webhooks events: How to subscribe to webhook events