Automatically deploying package builds

[oraNod]

Following on from discussion in #1869

Now that we are building package docs nightly in GHA, we should consider automatically deploying those builds to the devel branch on RTD: https://ansible.readthedocs.io/projects/ansible/devel/

We currently auto-deploy to devel on docs.ansible.com with the jenkins job on RH infra. Setting this up with the GHA builds would give us functional parity with the jenkins stuff. At some point we discussed it but decided to keep GHA build deployments on a manual trigger while we evaluate the new workflow.

There are other options for auto-deploying package builds too:

• Deploying nightlies to stage. This might be problematic because it would overwrite changes on stage, which might be annoying for experimental things that we want to leave up for more than a day.
• Deploying builds to latest. This could be risky because it is the version with the most visitors.

One thing to clarify, this does not apply to Ansible core documentation. In this context, the auto-deploy is for docs hosted on readthedocs. The Ansible core docs are automatically deployed using RTD settings and in its own project. The build package docs workflow is in a separate RTD project to core docs.

Tasks

Preview Give feedback

1. Decide on a strategy for automatically deploying builds
2. Restructure the package docs workflow and schedule nightly builds #2047
   0 of 3
   doc builds no_backport tooling +3
3. Build and deploy from the devel branch once a week, preferably at the start of the week #2049
   doc builds no_backport tooling +3
4. Build and deploy to latest once a week, running at the start of the week #2050
   doc builds no_backport tooling +3

[oraNod]

@samccann and @gotmax23 Let's continue the discussion here please. I've added the DaWGs label too.

One thing you mention about auto-deploys to latest @samccann :

I'm uncomfortable with autobuilds to /latest/ as that's the one that gets some rediculously-high number of views, like 40M a year? If something goes wrong, no one is looking at the build results until people start screaming.

When builds fail, we will get notifications in the docs channel in Matrix. The logs will also be readily available too so anyone who notices the docs-bot pings can take a look and triage the broken build. This is something we currently don't have with jenkins. One of us needs to go in and actually look at the builds.

In any case I do think it would be good to have a somewhat lower frequency of updates to latest and auto-deploy once a week or so on a Tuesday.

[samccann]

@oraNod To be clear, I'm not talking about a build failure, I'm talking about a successful build to /latest/ but the end result has some major failure for some reason. We've had it in the past where the docs published fine, only to realize some major gaps in what was available. As I said, it hasn't happened in a while, so it could have been an artifact of some older release process/tooling etc.

I think a weekly auto-deploy for latest is fine.

[oraNod]

we talked about this in the DaWGs meeting today and decided that we want to modify the workflow to:

• do nightly builds without any deployment twice a week
• build and deploy from the devel branch once a week, preferably at the start of the week
• build and deploy to latest once a week, also at the start of the week to avoid any failures going unnoticed at the weekend

[x1101]

So, looking through this trying to make some progress.

* do nightly builds without any deployment twice a week

Unless I'm reading something incorrectly here, the previously mentioned #1869 already enables actually nightly (well, at 0517) builds that are not deployed.

(this bit makes it seem like its not deployed)

check-deploy:
if: github.event_name == 'workflow_dispatch' && github.event.inputs.deploy == 'true'

So, if we're looking for "twice a week", do we simply want to change it from 17 5 * * * to 17 5 * * 1,3 (or similar)?

I'm still re-reading the workflows for the rest of this, but was going to start on the first point and it looks like its just down to some fine tuning, unless I'm off base.

[oraNod]

@x1101 that sounds right to me. we already have the nightly builds running but want to trim that down to twice a week. 17 5 * * 1,3 looks spot on.

the check-deploy thing is a condition that allows us to run the workflow on a schedule. the deploy-package-docs job relies on inputs that are null when triggered by a scheduled run, which causes the workflow to fail.

so if the user triggers the workflow manually and selects the deploy option, then check-deploy is true. in which case the deploy-package-docs job runs.

[x1101]

@oraNod does it make sense to break out the three items into separate "tasks" on this issue? I was going to tackle them one at a time and submit distinct PR's for each.

[webknjaz]

@oraNod I recommend putting the cron trigger into a separate workflow, making the original one reusable. This allows for better structure.

[oraNod]

@x1101 That makes sense to me, yes. I'll create those tasks for you now. I'll create another to tackle the recommendation from @webknjaz which could probably be a good place to start.

Also thanks for chiming in and pointing out the improvements @webknjaz much appreciated.

[oraNod]

OK @x1101 I've created the three tasks and converted them to issues. Hopefully all the details make sense there. Please take a look and comment on them so I can assign them to you. Any question, give us a shout. Thank you!