Add GitHub App integration type (#12273)

I'm treating the GHA integration as a remote integration, with just
enough configuration to display something in the UI.

I just stubbed in the handling of data from the GHA for now.

- Refs #12130
- Refs readthedocs/common#276
- Refs readthedocs/ext-theme#617

Author: agjohnson

common

@@ -0,0 +1,41 @@
+# Generated by Django 5.2.1 on 2025-06-30 23:10
+
+from django.db import migrations
+from django.db import models
+from django_safemigrate import Safe
+
+
+class Migration(migrations.Migration):
+    safe = Safe.always()
+
+    dependencies = [
+        ("integrations", "0014_add_index_speedup"),
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name="GitHubAppIntegration",
+            fields=[],
+            options={
+                "proxy": True,
+                "indexes": [],
+                "constraints": [],
+            },
+            bases=("integrations.integration",),
+        ),
+        migrations.AlterField(
+            model_name="integration",
+            name="integration_type",
+            field=models.CharField(
+                choices=[
+                    ("github_webhook", "GitHub incoming webhook"),
+                    ("bitbucket_webhook", "Bitbucket incoming webhook"),
+                    ("gitlab_webhook", "GitLab incoming webhook"),
+                    ("api_webhook", "Generic API incoming webhook"),
+                    ("githubapp", "GitHub App"),
+                ],
+                max_length=32,
+                verbose_name="Integration type",
+            ),
+        ),
+    ]

readthedocs/integrations/migrations/0015_add_github_app_integration.py

@@ -4,11 +4,13 @@
 import re
 import uuid
 
+from django.conf import settings
 from django.contrib.contenttypes.fields import GenericForeignKey
 from django.contrib.contenttypes.fields import GenericRelation
 from django.contrib.contenttypes.models import ContentType
 from django.db import models
 from django.db import transaction
+from django.urls import reverse
 from django.utils.crypto import get_random_string
 from django.utils.safestring import mark_safe
 from django.utils.translation import gettext_lazy as _
@@ -240,7 +242,16 @@ def get(self, *args, **kwargs):
         original = super().get(*args, **kwargs)
         return self._get_subclass_replacement(original)
 
-    def subclass(self, instance):
+    def subclass(self, instance=None):
+        """
+        Return a subclass or list of subclasses integrations.
+
+        If an instance was passed in, return a single subclasses integration
+        instance. If this is a queryset or manager, render the list as a list
+        using the integration subsclasses.
+        """
+        if instance is None:
+            return [self._get_subclass_replacement(_instance) for _instance in self]
         return self._get_subclass_replacement(instance)
 
     def create(self, **kwargs):
@@ -263,6 +274,7 @@ def create(self, **kwargs):
 class Integration(TimeStampedModel):
     """Inbound webhook integration for projects."""
 
+    GITHUBAPP = "githubapp"
     GITHUB_WEBHOOK = "github_webhook"
     BITBUCKET_WEBHOOK = "bitbucket_webhook"
     GITLAB_WEBHOOK = "gitlab_webhook"
@@ -275,7 +287,9 @@ class Integration(TimeStampedModel):
         (API_WEBHOOK, _("Generic API incoming webhook")),
     )
 
-    INTEGRATIONS = WEBHOOK_INTEGRATIONS
+    REMOTE_ONLY_INTEGRATIONS = ((GITHUBAPP, _("GitHub App")),)
+
+    INTEGRATIONS = WEBHOOK_INTEGRATIONS + REMOTE_ONLY_INTEGRATIONS
 
     project = models.ForeignKey(
         Project,
@@ -307,6 +321,8 @@ class Integration(TimeStampedModel):
 
     # Integration attributes
     has_sync = False
+    is_remote_only = False
+    is_active = True
 
     def __str__(self):
         return self.get_integration_type_display()
@@ -316,6 +332,9 @@ def save(self, *args, **kwargs):
             self.secret = get_random_string(length=32)
         super().save(*args, **kwargs)
 
+    def get_absolute_url(self) -> str:
+        return reverse("projects_integrations_detail", args=(self.project.slug, self.pk))
+
 
 class GitHubWebhook(Integration):
     integration_type_id = Integration.GITHUB_WEBHOOK
@@ -332,6 +351,47 @@ def can_sync(self):
             return False
 
 
+class GitHubAppIntegration(Integration):
+    integration_type_id = Integration.GITHUBAPP
+    has_sync = False
+    is_remote_only = True
+
+    class Meta:
+        proxy = True
+
+    def get_absolute_url(self) -> str | None:
+        """
+        Get URL of the GHA installation page.
+
+        Instead of showing a link to the integration details page, for GHA
+        projects we show a link in the UI to the GHA installation page for the
+        installation used by the project.
+        """
+        # If the GHA is disconnected we'll disonnect the remote repository and
+        # so we won't have a URL to the installation page the project should be
+        # using. We might want to store this on the model later so a repository
+        # that is removed from the installation can still link to the
+        # installation the project was _previously_ using.
+        try:
+            installation_id = self.project.remote_repository.github_app_installation.installation_id
+            return f"https://github.com/apps/{settings.GITHUB_APP_NAME}/installations/{installation_id}"
+        except AttributeError:
+            return None
+
+    @property
+    def is_active(self) -> bool:
+        """
+        Is the GHA connection active for this project?
+
+        This assumes that the status of the GHA connect will be reflected as
+        soon as there is an event that might disconnect the GHA on GitHub's
+        side -- uninstalling the app or revoking permission to the repository.
+        We listen for these events and should disconnect the remote
+        repository, but would leave this integration.
+        """
+        return self.project.is_github_app_project
+
+
 class BitbucketWebhook(Integration):
     integration_type_id = Integration.BITBUCKET_WEBHOOK
     has_sync = True

readthedocs/integrations/models.py

@@ -910,8 +910,19 @@ def get_queryset(self):
         return self.get_integration_queryset()
 
     def get_object(self):
+        integration = self.get_integration()
+        # Don't allow an integration detail page if the integration subclass
+        # does not support configuration
+        if integration.is_remote_only:
+            raise Http404
         return self.get_integration()
 
+    def get_context_data(self, **kwargs):
+        context = super().get_context_data(**kwargs)
+        if "object_list" in context:
+            context["subclassed_object_list"] = context["object_list"].subclass()
+        return context
+
     def get_integration_queryset(self):
         self.project = self.get_project()
         return self.model.objects.filter(project=self.project)

readthedocs/projects/views/private.py

@@ -20,6 +20,7 @@
     LATEST,
 )
 from readthedocs.builds.models import Build, Version
+from readthedocs.integrations.models import GitHubAppIntegration
 from readthedocs.integrations.models import GitHubWebhook, GitLabWebhook
 from readthedocs.oauth.constants import BITBUCKET, GITHUB, GITHUB_APP, GITLAB
 from readthedocs.oauth.models import (
@@ -78,6 +79,10 @@ def setUp(self):
         self.project = get(
             Project, users=[self.user], remote_repository=self.remote_repository
         )
+        self.integration = get(
+            GitHubAppIntegration,
+            project=self.project,
+        )
 
         self.remote_organization = get(
             RemoteOrganization,
@@ -1138,6 +1143,13 @@ def test_post_comment(self, request):
             "body": f"<!-- readthedocs-{another_project.id} -->\nComment from another project.",
         }
 
+    def test_integration_attributes(self):
+        assert self.integration.is_active
+        assert self.integration.get_absolute_url() == "https://github.com/apps/readthedocs/installations/1111"
+        self.project.remote_repository = None
+        assert not self.integration.is_active
+        assert self.integration.get_absolute_url() is None
+
 
 @override_settings(
     PUBLIC_API_URL="https://app.readthedocs.org",