Automatically deploy OpenAPI documents

[lcawl]

🚀 Request

Configure a pipeline for publishing OpenAPI documents.

Motivation

The Kibana OpenAPI documents are automatically deployed, which lightens the workload and possibility of error for docs release coordinators. The Elasticsearch OpenAPI documents should have similar automation.

Proposal

1. Store the final OpenAPI documents (or include the make overlay-docs command in the publishing pipeline).

2. Obtain the Bump.sh document details and store them in the vault secrets of your project.

3. Add steps to the appropriate pipelines for your project. For example, Kibana uses buildkite:publish_oas_docs.sh. Github actions are also possible per https://docs.bump.sh/help/continuous-integration/github-actions/

Here's another possible Buildkite pattern provided by @DaveSys911: "...Add the following example steps to the appropriate buildkite pipelines for your project...

env:
  ELASTIC_PR_COMMENTS_ENABLED: 'true'

steps:
# To be added to the buildkite pipeline set to run on prs
  # The doc name could be conditionally interpolated based on the branch name.
  # The easiset way would be to use an existing variable in the buildkite pipeline as a suffix(main|serverless).
  - label: ":mag: Check API diff"
    if: build.pull_request.base_branch =~ /main|\d\.\d/ && build.pull_request.id != null
    plugins:
      - elastic/vault-secrets#v0.0.3:
          path: "secret/ci/elastic-<your-repo>/<doc-token-path>"
          field: "bump-token" # OPTIONAL
          env_var: "BUMP_TOKEN" # OPTIONAL
    command: |
      - "bump api diff --doc $DOC_NAME --token $BUMP_TOKEN --file path/to/openapi.yml"
    agents:
      image: "docker.elastic.co/ci-agent-images/pipelib"

# Executes deployment logic when running on main or release branches
- label: ":rocket: Deploy API documentation"
    if: build.branch == 'main' && build.pull_request.id == null
    command:
      - "bump deploy --doc $DOC_NAME  --token $BUMP_TOKEN --file <file-name>"
    agents:
      image: "docker.elastic.co/ci-agent-images/pipelib"

...Adding a conditional on path changes to the doc paths of you project. Every project might have it's own way to detect file system changes. The following is an example of how to do it via the buildkite monorepo diff plugin"

steps:
  - label: "Triggering pipelines"
    plugins:
      - monorepo-diff#v1.0.1:
          diff: "git diff --name-only HEAD~1"
          watch:
            - path: path/to/openapi.yml
              config:
                command:  "buildkite-agent upload bump-sh-ci.sh"
                env:
                  DOC_NAME: "your-doc-name"