Set a commit status with the build result for all builds

[acoulton]

What's the problem this feature will solve?

Currently, it is hard to see whether merging changes to a Version branch has succeeded (without going to the separate RTD build status dashboard).

Describe the solution you'd like

I would like builds that are triggered from a push event (e.g. pushing or merging changes to a Version branch) to set a Github pending / failed / success status on the commit that triggered the build.

As far as I can see, at present this is only implemented for builds that are triggered by a Pull Request.

Alternative solutions

I don't think there are alternative solutions in the current build flow (other than the status quo, that users have to look at the RTD dashboard separately). Presenting the information in context in github would simplify the workflow, avoid confusion about when/whether changes have been published, and allow us to see the history of build success / failure alongside the code history.

Additional context

I've looked at the codebase to see how the PR commit statuses are set, and the code appears to confirm my understanding that RTD is explicitly / intentionally only setting a commit status for PR builds.

readthedocs.org/readthedocs/projects/tasks/utils.py

Lines 151 to 164 in 2993988

	def send_external_build_status(version_type, build_pk, commit, status):
	"""
	Check if build is external and Send Build Status for project external versions.
	:param version_type: Version type e.g EXTERNAL, BRANCH, TAG
	:param build_pk: Build pk
	:param commit: commit sha of the pull/merge request
	:param status: build status failed, pending, or success to be sent.
	"""
	# Send status reports for only External (pull/merge request) Versions.
	if version_type == EXTERNAL:
	# call the task that actually send the build status.
	send_build_status.delay(build_pk, commit, status)

I'm not certain of the history / rationale for this - it looks like it was originally implemented for all builds in 2019 but then restricted to PRs because we don't store the commit sha of a branch during code review.

I don't know if that's still the case and therefore still a blocker, or whether this would be easier to add now?

[humitos]

We tried to implemented this in 2023, but it was pretty complex and it was getting harder and harder to prioritize, so we decided to cancel that work. The implementation and the discussion lives in #10320

[acoulton]

Thanks for the response, I'd searched issues but not PRs so hadn't found that.

It looks like a lot of the complexity was due to storing the commit hash with the build as per the original conversation. However I noticed that the new build dashboard does show the commit hash for each version build so it's presumably stored somewhere:

Even if the commit hash isn't guaranteed to be present for every build, it would be very useful to report the commit status when there is one (which might be a simpler changeset)?