Buildkite PR job for assembling docs

[TrushynAliaksandr]

This PR introduces a Buildkite job to build pull requests. It replaces and combine the following Jenkins job:

• product repositories job Jenkins Job template
• elastic/docs Jenkins PR job

General approach

In the Jenkins world, we setup a dedicated job per repository with the job dsl coming from a template. We took a different approach in Buildkite, and instead setup a single Buildkite job that gets triggered for every PR builds on any of the docs product repo or the elastic/docs repo. This allows us to keep things tidy in Buildkite ( a single job) and limit considerably the amount of CI code to write in any product repository (see discussion on this approach here).

There are some downsides to this approach however:

• going to Buildkite build page looking for a specific build for a PR is not straight forward - it can be done by adding GET params to the builds url. For eg, to view the builds PR 3366 in elastic/observability-docs, we can visit the following URL: https://buildkite.com/elastic/docs-build-pr/builds?meta_data[repo_pr]=observability-docs_3366

• Since the same job is used for any PR in any of the product repositories, we allow concurrent builds of that job (otherwise, we could only run a single doc build at a time for any of the product repo). I have not seen/experienced/validated this yet, but we could run into scenarios where the same PR with 2 docs builds triggered in a short time frame try to push to the same preview branch and .

Docs repo configuration

We use the Buildkite PR bot in a non-conventional manner to achieve the above result:

• we use an "org-wide" configuration file stored in the master branch of elastic/docs - here (That file is not read in other branches).
• for all the products repositories, we leverage the "always_trigger_branch":true option. This is currently set to this branch while under development.
• for the elastic:docs repository, we use the default "always_trigger_branch":false option - since the build logic is stored within the elastic:docs repo - this is what would allow us to test out changes to the build logic itself.

Finally, the Buildkite PR bot allows for changes detections at certain path - this allows us to not trigger a PR build for every change in every docs repo, but only target doc changes.

With the above said, we have 3 configuration blobs in the PR bot config:

• product docs repo that should build for any change in the repo should be added here
• product docs repo that should build only when files within the ./docs folder should be added here
• config changes to elastic/docs is controlled here

The below config options have been configured for all of the above repositories:

• run docs-build
• run docs-build rebuild
• run docs-build warnlinkcheck
• run docs-build skiplinkcheck (takes precedence over the warnlinkcheck option)

PR job setup

When a docs PR job is opened / commented on, the Buildkite PR bot will trigger a docs-build-pr job, passing a few key env variables about the PR. The build script checks out that specific branch of the repository locally and references it in the build argument leveraging the --sub-dir option.

Similarly to Jenkins, PR on the elastic/docs repo always trigger a full rebuild.

PR are annotated with a link to the job preview and diff upon successful build - see example here.

Similar to other Buildkite job, docs preview changes are pushed to the bk branch until the migration is complete.

pre/post command hooks

We're leveraging theses the pre-command hook to setup the build commit status to pending and the post-commit one to success and failure. At this time, we're re-using the GITHUB token from the preview-cleaner job that has sufficient permissions to do such API calls.

All of the perms (to clone repo, commit) are tied to elasticmachine - I suspect this may have to change at some point in the future, but that's the current setup.

Jenkins/Buildkite comparison

Example of jobs that ran, and the differences between Jenkins and Buildkite, and the diff between the built-docs branches.

• [do not merge] testing out doc change for Buildkite observability-docs#3366 - diff
• https://github.com/elastic/tech-content/pull/382 - diff
• [do not merge] validating buildkite builds in docs repo #2833 - diff
• [do not merge] testing out doc change for Buildkite on forks observability-docs#3373 - diff

Note - on the docs changes in the docs repo, we're seeing images conflicts and changes - see convo about it here.

[TrushynAliaksandr]

To do:

• Add set_commit_status to the master: elastic/docs repository and think about how we can get the status after the end of the pipeline (now only the pending status is set)
• Add other required repositories to the org-wide config and create webhook for each
• Write documentation for buildkite updates
• Cleanup Jenkins builds

[nkammah]

This does not seem to work as expected - see this build - the preview URL was set to

https://docs_bk_false.docs-preview.app.elstc.co/diff
instead of
https://docs_bk_2805.docs-preview.app.elstc.co/diff

the issue being with this line

BUILDKITE_PULL_REQUEST is a boolean - in this case it was set to false, even though it was an actual PR. A better approach may be to check the value of GITHUB_PR_NUMBER.

[nkammah]

run docs-build rebuild warnlinkcheck

[nkammah]

Closing this PR - will open a new one under my name.