How to set up docs previews

This guide will help you set up docs previews for your GitHub repository.

The docs preview system consists of two GitHub Workflows:

• docs-build.yml: Build the docs on a PR
• docs-cleanup.yml: Cleanup the docs after a PR is merged or closed

This workflow is triggered when a PR is opened. The underlying reusable workflow, builds the documentation and uploads it as an artifact.
If the path-pattern input does not match any changes in the PR, the workflow will skip the build, but still set a green status check.
This way you only build and deploy the docs when there are changes to the docs and you can still set it as a required status check.

---
name: docs-build

on:
  push:
    branches: 
        - main 1
  pull_request_target: ~

jobs:
  docs-preview:
    uses: elastic/docs-builder/.github/workflows/preview-build.yml 2
    with:
      path-pattern: docs/** 3
    permissions:
      id-token: write
      deployments: write
      contents: read
      pull-requests: read

This workflow is triggered when a PR is either merged or closed. The underlying reusable workflow, deletes the docs from the preview environment.

---
name: docs-cleanup

on:
  pull_request_target:
    types:
      - closed

jobs:
  docs-preview:
    uses: elastic/docs-builder/.github/workflows/preview-cleanup.yml 1
    permissions:
      contents: none 2
      id-token: write
      deployments: write

To ensure that the docs are always in a deployable state, we need to set up required status checks.

In this case only the docs-build workflow is required, which will produce a status check named docs-preview / build.

If the docs-build workflow is successful, the docs-deploy workflow will create a deployment visible in the GitHub UI on your PR.