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

# Configure a Github integration for self-hosted Lightdash

<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](/references/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`

<img src="https://mintcdn.com/lightdash-mintlify-ca973f84/Cv-EyrsapF-673yr/images/self-host/customize-deployment/configure-github-for-lightdash/github-create-app.png?fit=max&auto=format&n=Cv-EyrsapF-673yr&q=85&s=3ed89bad8a65c8ec6fe19633d4835a48" alt="Github Create App Pn" width="950" height="467" data-path="images/self-host/customize-deployment/configure-github-for-lightdash/github-create-app.png" />

**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`

   <img src="https://mintcdn.com/lightdash-mintlify-ca973f84/xzMB98TbfJL65AbG/images/self-host/customize-deployment/configure-github-for-lightdash/github-oauth-refresh-token.png?fit=max&auto=format&n=xzMB98TbfJL65AbG&q=85&s=666465e7bedc4a93b608a5487c659a04" 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" />
7. Enable \*\*Redirect on update \*\*on Post Installation
8. Deactivate webhooks

   <img src="https://mintcdn.com/lightdash-mintlify-ca973f84/Cv-EyrsapF-673yr/images/self-host/customize-deployment/configure-github-for-lightdash/github-deactivate-webhooks.png?fit=max&auto=format&n=Cv-EyrsapF-673yr&q=85&s=3a9339076d0c9c59647b0956b1122e1f" alt="Github Deactivate Webhooks Pn" width="756" height="295" data-path="images/self-host/customize-deployment/configure-github-for-lightdash/github-deactivate-webhooks.png" />

**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.

<img src="https://mintcdn.com/lightdash-mintlify-ca973f84/Cv-EyrsapF-673yr/images/self-host/customize-deployment/configure-github-for-lightdash/github-generate-client-secret.png?fit=max&auto=format&n=Cv-EyrsapF-673yr&q=85&s=e9ca4b06cb980f21829fe72361993fb9" 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" />

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.

<img src="https://mintcdn.com/lightdash-mintlify-ca973f84/xzMB98TbfJL65AbG/images/self-host/customize-deployment/configure-github-for-lightdash/github-generate-private-key.png?fit=max&auto=format&n=xzMB98TbfJL65AbG&q=85&s=5c84ff6e07a151339e23ba8be3edf68f" 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" />

<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.