Send Build Status Report Using GitHub Status API

readthedocs/builds/constants.py

@@ -61,3 +61,37 @@
     LATEST,
     STABLE,
 )
+
+# GitHub Build Statuses
+GITHUB_BUILD_STATE_FAILURE = 'failure'
+GITHUB_BUILD_STATE_PENDING = 'pending'
+GITHUB_BUILD_STATE_SUCCESS = 'success'
+
+# GitLab Build Statuses
+GITLAB_BUILD_STATE_FAILURE = 'failed'
+GITLAB_BUILD_STATE_PENDING = 'pending'
+GITLAB_BUILD_STATE_SUCCESS = 'success'
+
+# General Build Statuses
+BUILD_STATUS_FAILURE = 'failed'
+BUILD_STATUS_PENDING = 'pending'
+BUILD_STATUS_SUCCESS = 'success'
+
+# Used to select correct Build status and description to be sent to each service API
+SELECT_BUILD_STATUS = {
+    BUILD_STATUS_FAILURE: {
+        'github': GITHUB_BUILD_STATE_FAILURE,
+        'gitlab': GITLAB_BUILD_STATE_FAILURE,
+        'description': 'The build failed!',
+    },
+    BUILD_STATUS_PENDING: {
+        'github': GITHUB_BUILD_STATE_PENDING,
+        'gitlab': GITLAB_BUILD_STATE_PENDING,
+        'description': 'The build is pending!',
+    },
+    BUILD_STATUS_SUCCESS: {
+        'github': GITHUB_BUILD_STATE_SUCCESS,
+        'gitlab': GITLAB_BUILD_STATE_SUCCESS,
+        'description': 'The build succeeded!',
+    },
+}

readthedocs/builds/models.py

@@ -734,6 +734,14 @@ def __str__(self):
     def get_absolute_url(self):
         return reverse('builds_detail', args=[self.project.slug, self.pk])
 
+    def get_full_url(self):
+        """Get full url including domain"""
+        full_url = 'https://{domain}{absolute_url}'.format(
+            domain=settings.PRODUCTION_DOMAIN,
+            absolute_url=self.get_absolute_url()
+        )
+        return full_url
+
     @property
     def finished(self):
         """Return if build has a finished state."""

readthedocs/core/utils/__init__.py

@@ -11,7 +11,10 @@
 from django.utils.safestring import SafeText, mark_safe
 from django.utils.text import slugify as slugify_base
 
-from readthedocs.builds.constants import BUILD_STATE_TRIGGERED
+from readthedocs.builds.constants import (
+    BUILD_STATE_TRIGGERED,
+    BUILD_STATUS_PENDING,
+)
 from readthedocs.doc_builder.constants import DOCKER_LIMITS
 
 
@@ -78,7 +81,10 @@ def prepare_build(
     # Avoid circular import
     from readthedocs.builds.models import Build
     from readthedocs.projects.models import Project
-    from readthedocs.projects.tasks import update_docs_task
+    from readthedocs.projects.tasks import (
+        update_docs_task,
+        send_external_build_status,
+    )
 
     build = None
 
@@ -125,6 +131,10 @@ def prepare_build(
     options['soft_time_limit'] = time_limit
     options['time_limit'] = int(time_limit * 1.2)
 
+    if build:
+        # Send pending Build Status using Git Status API for External Builds.
+        send_external_build_status(build.id, BUILD_STATUS_PENDING)
+
     return (
         update_docs_task.signature(
             args=(version.pk,),

readthedocs/doc_builder/environments.py

@@ -658,7 +658,7 @@ def failed(self):
     def done(self):
         """Is build in finished state."""
         return (
-            self.build is not None and
+            self.build and
             self.build['state'] == BUILD_STATE_FINISHED
         )
 

readthedocs/oauth/services/base.py

@@ -216,6 +216,9 @@ def setup_webhook(self, project):
     def update_webhook(self, project, integration):
         raise NotImplementedError
 
+    def send_build_status(self, build, state):
+        raise NotImplementedError
+
     @classmethod
     def is_project_service(cls, project):
         """

readthedocs/oauth/services/github.py

@@ -12,6 +12,7 @@
 
 from readthedocs.api.v2.client import api
 from readthedocs.builds import utils as build_utils
+from readthedocs.builds.constants import SELECT_BUILD_STATUS
 from readthedocs.integrations.models import Integration
 
 from ..models import RemoteOrganization, RemoteRepository
@@ -311,6 +312,80 @@ def update_webhook(self, project, integration):
             )
             return (False, resp)
 
+    def send_build_status(self, build, state):
+        """
+        Create GitHub commit status for project.
+
+        :param build: Build to set up commit status for
+        :type build: Build
+        :param state: build state failure, pending, or success.
+        :type state: str
+        :returns: boolean based on commit status creation was successful or not.
+        :rtype: Bool
+        """
+        session = self.get_session()
+        project = build.project
+        owner, repo = build_utils.get_github_username_repo(url=project.repo)
+        build_sha = build.version.identifier
+
+        # select the correct state and description.
+        github_build_state = SELECT_BUILD_STATUS[state]['github']
+        description = SELECT_BUILD_STATUS[state]['description']
+
+        data = {
+            'state': github_build_state,
+            'target_url': build.get_full_url(),
+            'description': description,
+            'context': 'continuous-documentation/read-the-docs'
+        }
+
+        resp = None
+
+        try:
+            resp = session.post(
+                f'https://api.github.com/repos/{owner}/{repo}/statuses/{build_sha}',
+                data=json.dumps(data),
+                headers={'content-type': 'application/json'},
+            )
+            if resp.status_code == 201:
+                log.info(
+                    'GitHub commit status for project: %s',
+                    project,
+                )
+                return True
+
+            if resp.status_code in [401, 403, 404]:
+                log.info(
+                    'GitHub project does not exist or user does not have '
+                    'permissions: project=%s',
+                    project,
+                )
+                return False
+
+            return False
+
+        # Catch exceptions with request or deserializing JSON
+        except (RequestException, ValueError):
+            log.exception(
+                'GitHub commit status creation failed for project: %s',
+                project,
+            )
+            # Response data should always be JSON, still try to log if not
+            # though
+            if resp is not None:
+                try:
+                    debug_data = resp.json()
+                except ValueError:
+                    debug_data = resp.content
+            else:
+                debug_data = resp
+
+            log.debug(
+                'GitHub commit status creation failure response: %s',
+                debug_data,
+            )
+            return False
+
     @classmethod
     def get_token_for_project(cls, project, force_local=False):
         """Get access token for project by iterating over project users."""

readthedocs/projects/tasks.py

@@ -34,6 +34,9 @@
     LATEST,
     LATEST_VERBOSE_NAME,
     STABLE_VERBOSE_NAME,
+    EXTERNAL,
+    BUILD_STATUS_SUCCESS,
+    BUILD_STATUS_FAILURE,
 )
 from readthedocs.builds.models import APIVersion, Build, Version
 from readthedocs.builds.signals import build_complete
@@ -59,6 +62,8 @@
 )
 from readthedocs.doc_builder.loader import get_builder_class
 from readthedocs.doc_builder.python_environments import Conda, Virtualenv
+from readthedocs.oauth.models import RemoteRepository
+from readthedocs.oauth.services.github import GitHubService
 from readthedocs.projects.models import APIProject, Feature
 from readthedocs.search.utils import index_new_files, remove_indexed_files
 from readthedocs.sphinx_domains.models import SphinxDomain
@@ -573,6 +578,15 @@ def run_build(self, docker, record):
 
         if self.build_env.failed:
             self.send_notifications(self.version.pk, self.build['id'])
+            # send build failure status to git Status API
+            self.send_build_status(
+                self.build['id'], BUILD_STATUS_FAILURE
+            )
+        elif self.build_env.successful:
+            # send build successful status to git Status API
+            self.send_build_status(
+                self.build['id'], BUILD_STATUS_SUCCESS
+            )
 
         build_complete.send(sender=Build, build=self.build_env.build)
 
@@ -1008,6 +1022,10 @@ def is_type_sphinx(self):
         """Is documentation type Sphinx."""
         return 'sphinx' in self.config.doctype
 
+    def send_build_status(self, build_pk, state):
+        """Send github build status for pull/merge requests."""
+        send_external_build_status(build_pk, state)
+
 
 # Web tasks
 @app.task(queue='web')
@@ -1513,8 +1531,11 @@ def _manage_imported_files(version, path, commit, build):
 @app.task(queue='web')
 def send_notifications(version_pk, build_pk):
     version = Version.objects.get_object_or_log(pk=version_pk)
-    if not version:
+
+    # only send notification for Internal versions
+    if not version or version.type == EXTERNAL:
         return
+
     build = Build.objects.get(pk=build_pk)
 
     for hook in version.project.webhook_notifications.all():
@@ -1773,3 +1794,45 @@ def retry_domain_verification(domain_pk):
         sender=domain.__class__,
         domain=domain,
     )
+
+
+@app.task(queue='web')
+def send_build_status(build, state):
+    """
+    Send Build Status to Git Status API for project external versions.
+
+    :param build: Build
+    :param state: build state failed, pending, or success to be sent.
+    """
+    try:
+        if build.project.remote_repository.account.provider == 'github':
+            service = GitHubService(
+                build.project.remote_repository.users.first(),
+                build.project.remote_repository.account
+            )
+
+            # send Status report using the API.
+            service.send_build_status(build, state)
+
+    except RemoteRepository.DoesNotExist:
+        log.info('Remote repository does not exist for %s', build.project)
+
+    except Exception:
+        log.exception('Send build status task failed for %s', build.project)
+
+    # TODO: Send build status for other providers.
+
+
+def send_external_build_status(build_pk, state):
+    """
+    Check if build is external and Send Build Status for project external versions.
+
+    :param build_pk: Build pk
+    :param state: build state failed, pending, or success to be sent.
+    """
+    build = Build.objects.get(pk=build_pk)
+
+    # Send status reports for only External (pull/merge request) Versions.
+    if build.version.type == EXTERNAL:
+        # call the task that actually send the build status.
+        send_build_status.delay(build, state)

readthedocs/rtd_tests/tests/test_api.py

@@ -906,7 +906,8 @@ def test_github_create_event(self, sync_repository_task, trigger_build):
         latest_version = self.project.versions.get(slug=LATEST)
         sync_repository_task.delay.assert_called_with(latest_version.pk)
 
-    def test_github_pull_request_opened_event(self, trigger_build):
+    @mock.patch('readthedocs.core.utils.trigger_build')
+    def test_github_pull_request_opened_event(self, trigger_build, core_trigger_build):
         client = APIClient()
 
         headers = {GITHUB_EVENT_HEADER: GITHUB_PULL_REQUEST}
@@ -925,12 +926,13 @@ def test_github_pull_request_opened_event(self, trigger_build):
         self.assertTrue(resp.data['build_triggered'])
         self.assertEqual(resp.data['project'], self.project.slug)
         self.assertEqual(resp.data['versions'], [external_version.verbose_name])
-        trigger_build.assert_called_once_with(
+        core_trigger_build.assert_called_once_with(
             force=True, project=self.project, version=external_version
         )
         self.assertTrue(external_version)
 
-    def test_github_pull_request_reopened_event(self, trigger_build):
+    @mock.patch('readthedocs.core.utils.trigger_build')
+    def test_github_pull_request_reopened_event(self, trigger_build, core_trigger_build):
         client = APIClient()
 
         # Update the payload for `reopened` webhook event
@@ -955,12 +957,13 @@ def test_github_pull_request_reopened_event(self, trigger_build):
         self.assertTrue(resp.data['build_triggered'])
         self.assertEqual(resp.data['project'], self.project.slug)
         self.assertEqual(resp.data['versions'], [external_version.verbose_name])
-        trigger_build.assert_called_once_with(
+        core_trigger_build.assert_called_once_with(
             force=True, project=self.project, version=external_version
         )
         self.assertTrue(external_version)
 
-    def test_github_pull_request_synchronize_event(self, trigger_build):
+    @mock.patch('readthedocs.core.utils.trigger_build')
+    def test_github_pull_request_synchronize_event(self, trigger_build, core_trigger_build):
         client = APIClient()
 
         pull_request_number = '6'
@@ -998,13 +1001,14 @@ def test_github_pull_request_synchronize_event(self, trigger_build):
         self.assertTrue(resp.data['build_triggered'])
         self.assertEqual(resp.data['project'], self.project.slug)
         self.assertEqual(resp.data['versions'], [external_version.verbose_name])
-        trigger_build.assert_called_once_with(
+        core_trigger_build.assert_called_once_with(
             force=True, project=self.project, version=external_version
         )
         # `synchronize` webhook event updated the identifier (commit hash)
         self.assertNotEqual(prev_identifier, external_version.identifier)
 
-    def test_github_pull_request_closed_event(self, trigger_build):
+    @mock.patch('readthedocs.core.utils.trigger_build')
+    def test_github_pull_request_closed_event(self, trigger_build, core_trigger_build):
         client = APIClient()
 
         pull_request_number = '7'
@@ -1044,7 +1048,7 @@ def test_github_pull_request_closed_event(self, trigger_build):
         self.assertTrue(resp.data['version_deleted'])
         self.assertEqual(resp.data['project'], self.project.slug)
         self.assertEqual(resp.data['versions'], [version.verbose_name])
-        trigger_build.assert_not_called()
+        core_trigger_build.assert_not_called()
 
     def test_github_pull_request_no_action(self, trigger_build):
         client = APIClient()