Skip to content

Clarify new/existing GitHub App installation documentation #99

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Jul 28, 2025
Merged

Clarify new/existing GitHub App installation documentation #99

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
9e62ebd
Clarify new/existing GitHub App installation documentation
joshuadavidthomas Jul 28, 2025
3ac782a
plural
joshuadavidthomas Jul 28, 2025
11e638a
[pre-commit.ci] auto fixes from pre-commit.com hooks
pre-commit-ci[bot] Jul 28, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
30 changes: 25 additions & 5 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -107,7 +107,7 @@ cog.outl(f"- Django {', '.join([version for version in DJ_VERSIONS if version !=
> - Use `"async"` with `AsyncWebhookView`
> - Use `"sync"` with `SyncWebhookView`

5. Setup your GitHub App, either by registering a new one or importing an existing one, and configure django-github-app using your GitHub App's information.
5. Setup your GitHub App and configure django-github-app using your GitHub App's information.

You will need the following information from your GitHub App:

Expand Down Expand Up @@ -136,7 +136,22 @@ cog.outl(f"- Django {', '.join([version for version in DJ_VERSIONS if version !=
>
> django-github-app will automatically detect if `GITHUB_APP["PRIVATE_KEY"]` is a path and load the file contents. For more information, see the [`PRIVATE_KEY`](#private_key) section in the [Configuration](#configuration) documentation below.

### Create a New GitHub App
### GitHub App Setup

After completing the [Installation](#installation) steps above, you will need to set up your GitHub App using the information from Step 5 above.

Choose the appropriate setup method based on your situation:

- **[Create a New GitHub App](#create-a-new-github-app)**: If you're setting up a fresh GitHub App
- **[Use an Existing GitHub App](#use-an-existing-github-app-and-installation)**: If your GitHub App is already installed on organizations/repositories

> [!IMPORTANT]
> django-github-app needs to create `Installation` and `Repository` models in your database to track where your GitHub App is installed. How this happens depends on your setup method:
>
> - **New GitHub App**: When you install the app for the first time, GitHub sends an `installation.created` webhook event. django-github-app automatically creates the necessary models when it receives this event.
> - **Existing GitHub App**: If the app is already installed, no `installation.created` webhook event is sent. You must use the `github import-app` management command to manually create the models.

#### Create a New GitHub App

1. Register a new GitHub App, following [these instructions](https://docs.github.com/en/apps/creating-github-apps/registering-a-github-app/registering-a-github-app) from the GitHub Docs. For a more detailed tutorial, there is also [this page](https://docs.github.com/en/apps/creating-github-apps/writing-code-for-a-github-app/building-a-github-app-that-responds-to-webhook-events) -- in particular the section on [Setup](https://docs.github.com/en/apps/creating-github-apps/writing-code-for-a-github-app/building-a-github-app-that-responds-to-webhook-events#setup).

Expand Down Expand Up @@ -169,9 +184,11 @@ cog.outl(f"- Django {', '.join([version for version in DJ_VERSIONS if version !=
- Select the account to install it on
- Choose which repositories to give it access to

When you install the app, django-github-app will automatically create the necessary `Installation` and `Repository` models when it receives the `installation.created` webhook event.
When you install the app **for the first time**, django-github-app will automatically create the necessary `Installation` and `Repository` models when it receives the `installation.created` webhook event.

#### Use an Existing GitHub App and Installation

### Use an Existing GitHub App and Installation
If your GitHub App is already installed on organizations/repositories, the `installation.created` webhook event won't be sent when you connect django-github-app to your existing app. In this case, you need to manually import the installation data.

1. Collect your existing app and installation's information.

Expand Down Expand Up @@ -199,7 +216,7 @@ cog.outl(f"- Django {', '.join([version for version in DJ_VERSIONS if version !=
}
```

3. Import your existing GitHub App by using the `github import-app` management command.
3. Import your existing GitHub App by using the `github import-app` management command to create the necessary `Installation` and `Repository` models.

```bash
python manage.py github import-app --type user --name <username> --installation-id 123456
Expand All @@ -209,6 +226,9 @@ cog.outl(f"- Django {', '.join([version for version in DJ_VERSIONS if version !=
uv run manage.py github import-app --type user --name <username> --installation-id 123456
```

> [!NOTE]
> After importing, django-github-app will handle future webhook events normally, including repository additions/removals via the `installation_repositories` event.

## Getting Started

### Webhook Events
Expand Down