> ## Documentation Index
> Fetch the complete documentation index at: https://lightdash-mintlify-0fc6449e.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Configure a Github integration for self-hosted Lightdash

> Create a GitHub app and wire its credentials into your instance so Lightdash can write to dbt repos

<Note>
  🛠 This page is for engineering teams self-hosting their own Lightdash instance. If you want to use the GitHub integration, go to the [dbt projects](/integrations/dbt/projects) guide.
</Note>

In this guide we will show you how you can enable the Github integration on your on self-hosted Lightdash server.

### Create a new Github app

Go to app settings in Github, either organization or account developer settings and click `New Github App`

<Frame>
  <img src="https://mintcdn.com/lightdash-mintlify-0fc6449e/NmNYIGXmi1irS8lZ/images/self-host/customize-deployment/configure-github-for-lightdash/github-create-app.png?fit=max&auto=format&n=NmNYIGXmi1irS8lZ&q=85&s=4f8a7c62e663a8f59edc1f86ed2a294c" alt="Github Create App Pn" width="950" height="467" data-path="images/self-host/customize-deployment/configure-github-for-lightdash/github-create-app.png" />
</Frame>

**Settings:**

1. Set the app name: must be unique across Github
2. Add a description
3. Homepage URL: e.g. `https://lightdash.com`
4. Callback URL: `https://<your-domain>/api/v1/github/oauth/callback`
5. Enable `Expire user authorization tokens`
6. Enable `Request user authorization (OAuth) during installation`

   <Frame>
     <img src="https://mintcdn.com/lightdash-mintlify-0fc6449e/NmNYIGXmi1irS8lZ/images/self-host/customize-deployment/configure-github-for-lightdash/github-oauth-refresh-token.png?fit=max&auto=format&n=NmNYIGXmi1irS8lZ&q=85&s=04b2d525b35e1a288a2ad56c3d57a546" alt="Github Oauth Refresh Token Pn" width="760" height="308" data-path="images/self-host/customize-deployment/configure-github-for-lightdash/github-oauth-refresh-token.png" />
   </Frame>
7. Enable \*\*Redirect on update \*\*on Post Installation
8. Deactivate webhooks

   <Frame>
     <img src="https://mintcdn.com/lightdash-mintlify-0fc6449e/NmNYIGXmi1irS8lZ/images/self-host/customize-deployment/configure-github-for-lightdash/github-deactivate-webhooks.png?fit=max&auto=format&n=NmNYIGXmi1irS8lZ&q=85&s=35c08ca1f7131fa42b9e5d981631b1c0" alt="Github Deactivate Webhooks Pn" width="756" height="295" data-path="images/self-host/customize-deployment/configure-github-for-lightdash/github-deactivate-webhooks.png" />
   </Frame>

**Repository Permissions:**

* Checks: `Read and write`
* Contents: `Read and write`
* Pull requests: `Read and write`
* Workflows (optional): `Read and write`

**Account Permissions:** None

**Where can this GitHub App be installed?** Any account

### **Generate Certificate and Secret**

After creating your Github account you will need to generate a Client Secret.

Copy it and keep it safe, this will get used for the `GITHUB_CLIENT_SECRET` environment variable.

<Frame>
  <img src="https://mintcdn.com/lightdash-mintlify-0fc6449e/NmNYIGXmi1irS8lZ/images/self-host/customize-deployment/configure-github-for-lightdash/github-generate-client-secret.png?fit=max&auto=format&n=NmNYIGXmi1irS8lZ&q=85&s=30eaf7deaaaafb2e0e747a6d24d91314" alt="Github Generate Client Secret Pn" width="742" height="124" data-path="images/self-host/customize-deployment/configure-github-for-lightdash/github-generate-client-secret.png" />
</Frame>

And a Private Key.

Convert the contents of the private key file into `base64` , this will get used for the `GITHUB_PRIVATE_KEY` environment variable.

<Frame>
  <img src="https://mintcdn.com/lightdash-mintlify-0fc6449e/NmNYIGXmi1irS8lZ/images/self-host/customize-deployment/configure-github-for-lightdash/github-generate-private-key.png?fit=max&auto=format&n=NmNYIGXmi1irS8lZ&q=85&s=d09173e8bd4707e6840a89a64d446f46" alt="Github Generate Private Key Pn" width="794" height="336" data-path="images/self-host/customize-deployment/configure-github-for-lightdash/github-generate-private-key.png" />
</Frame>

<Info>
  You should save both the Client Secret and the Private Key in a safe place as you might need them at a later time.
</Info>

### Adding credentials to your local environment

Now you need to add the following environment variables to your Lightdash server.

* `GITHUB_PRIVATE_KEY` : This is the `base64` string of the Private Key generated for your Github app
* `GITHUB_CLIENT_SECRET` : This is the client secret generated for your Github app
* `GITHUB_CLIENT_ID`: Copy this from your Github app settings > General
* `GITHUB_APP_ID`: Copy this from your Github app settings > General
* `GITHUB_APP_NAME`: This is the name you set for your app, you can find it in app settings.