You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/configure/content-sources.md
+13-10Lines changed: 13 additions & 10 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -48,30 +48,33 @@ To get started:
48
48
49
49
#### CI configuration
50
50
51
-
To ensure repositories that use the [tagged branching strategy](#tagged) can be onboarded correctly, our CI integration needs to have appropriate `push`
52
-
branch triggers.
51
+
To ensure repositories that use the [tagged branching strategy](#tagged) can be onboarded correctly, our CI integration needs appropriate `push` branch triggers and matching settings on the reusable workflows in [`elastic/docs-actions`](https://github.com/elastic/docs-actions).
52
+
53
+
Also add **`docs-deploy.yml`** and **`docs-preview-cleanup.yml`** as described in [How to set up docs previews](../migration/guide/how-to-set-up-docs-previews.md); the snippet below only highlights the tagged-branching-specific parts of **docs-build** (and the same `with:` block must be passed through on your **docs-deploy** consumer job).
1. Ensure version branches are built and publish their links ahead of time.
80
+
2. Matches **docs-deploy** `with:` (`path-pattern`, `use-release-branches`) so release-line pushes still produce `links.json` when needed even if `docs/**` is unchanged for a long time.
Add the documentation CI workflows to the `.github/workflows` directory. Reusable workflows are maintained in [`elastic/docs-actions`](https://github.com/elastic/docs-actions); consumer repos add **`docs-build.yml`**, **`docs-deploy.yml`**, and **`docs-preview-cleanup.yml`** that call those workflows at `@v1`. Follow [How to set up docs previews](../migration/guide/how-to-set-up-docs-previews.md) for full YAML and permissions.
45
42
46
43
Then, successfully run a docs build on the `main` branch. This is a requirement. For example, you can merge a docs pull request to `main` after adding the workflow actions.
This guide will help you set up docs previews for your GitHub repository.
4
4
5
-
## GitHub Workflows
5
+
Reusable workflows live in [`elastic/docs-actions`](https://github.com/elastic/docs-actions). Pin them to **`@v1`** so the docs team can ship updates independently of [`elastic/docs-builder`](https://github.com/elastic/docs-builder). Reference repos: [elastic/elastic-otel-rum-js](https://github.com/elastic/elastic-otel-rum-js), [elastic/ecs-logging-nodejs](https://github.com/elastic/ecs-logging-nodejs).
6
6
7
-
The docs preview system consists of two GitHub Workflows:
8
-
-[`docs-build.yml`](#build): **Build** the docs on a PR
9
-
-[`docs-cleanup.yml`](#cleanup): **Cleanup** the docs after a PR is merged or closed
7
+
## GitHub workflows
8
+
9
+
The integration uses **three** workflows:
10
+
11
+
-[`docs-build.yml`](#build) — Required checks: validate and build docs in an unprivileged context (`pull_request`, `push`, `merge_group`).
12
+
-[`docs-deploy.yml`](#deploy) — Runs after `docs-build` completes (`workflow_run`). Handles preview deployment, PR comments, and org checks; never checks out untrusted code before gating.
13
+
-[`docs-preview-cleanup.yml`](#preview-cleanup) — Removes preview artifacts when a PR is closed (`pull_request_target`).
14
+
15
+
This follows GitHub’s [recommended two-phase approach](https://securitylab.github.com/resources/github-actions-preventing-pwn-requests/) for fork PRs: the **build** workflow uses `pull_request` (not `pull_request_target`) for the main validation path.
10
16
11
17
12
18
### Build
13
19
14
-
This workflow is triggered when a PR is opened. The underlying reusable workflow, builds the documentation and uploads it as an artifact.
15
-
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.
16
-
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.
20
+
This workflow runs on pull requests, pushes to your default branch (and optionally release branches), and merge queue events. The reusable workflow builds the documentation and uploads artifacts for the deploy phase.
17
21
22
+
If the `path-pattern` input does not match any changes in the PR, the workflow can skip the heavy build while still reporting a successful status check, so you can keep **docs-build** as a required check. The default path pattern is `docs/**` (see [optional inputs](#optional-workflow-inputs)).
18
23
19
24
::::{tab-set}
20
25
@@ -25,83 +30,141 @@ This way you only build and deploy the docs when there are changes to the docs a
This workflow runs when **docs-build** finishes. It downloads artifacts, deploys previews, manages GitHub deployments, and may post or update PR comments. It does **not** use `pull_request_target` on the PR head for the same event as the build; it is triggered via `workflow_run` after the build workflow completes.
60
+
61
+
::::{tab-set}
62
+
63
+
:::{tab-item} .github/workflows/docs-deploy.yml
64
+
65
+
```yaml
66
+
---
67
+
name: docs-deploy
68
+
69
+
on:
70
+
workflow_run:
71
+
workflows: [docs-build]
72
+
types: [completed]
57
73
58
-
This workflow is triggered when a PR is either merged or closed. The underlying reusable workflow, deletes the docs from the preview environment.
This workflow runs when a PR is **closed** (merged or not). It deletes preview content from the preview environment.
59
96
60
97
:::{note}
61
-
We are aware of the security implications of using `pull_request_target` as described in [this blog post](https://securitylab.github.com/resources/github-actions-preventing-pwn-requests/).
62
-
The workflow never checks out the code and doesn't use any user modifiable inputs (e.g. PR title).
98
+
Using `pull_request_target` here is intentional. As in GitHub’s guidance, this workflow should **not** check out the PR head for arbitrary code execution with elevated secrets. The reusable cleanup workflow follows that model.
2. No permission to read repository contents from the workflow token as provided here; adjust only if your org policy requires a different matrix.
89
125
90
126
:::
91
127
92
128
::::
93
129
94
-
## Required Status Checks
95
130
96
-
To ensure that the docs are always in a deployable state, we need to set up required status checks.
131
+
### Fork pull requests
132
+
133
+
Contributors opening PRs from forks still get **build validation** from **docs-build**. Preview **deploy** for fork PRs may depend on membership checks in the deploy workflow. That logic is implemented in `docs-actions` (for example, [elastic/docs-actions#85](https://github.com/elastic/docs-actions/pull/85) — org membership is verified via the GitHub API; contributors do **not** need to change Elastic org visibility on their public profile for that check).
134
+
135
+
136
+
### Optional workflow inputs
137
+
138
+
Pass `with:` on the **`uses:`** line when you need non-default behavior (for example documentation outside `docs/`, [tagged branching](../../configure/content-sources.md), or Vale). Inputs are defined on each reusable workflow’s `workflow_call` interface — see the files under [`.github/workflows/`](https://github.com/elastic/docs-actions/tree/main/.github/workflows) in `docs-actions`.
139
+
140
+
Common cases:
97
141
98
-
In this case only the `docs-build` workflow is required, which will produce a status check named `docs-preview / build`.
142
+
- **`path-pattern`** — Glob for which paths count as doc changes (default `docs/**`). If you set it on **docs-build**, use the **same** values on **docs-deploy** so both phases agree.
143
+
- **`use-release-branches`** — Set to `true` on **both** build and deploy when you use semver release branches (for example `8.11`) and need link-index / build behavior on pushes that do not touch `docs/**`. See [CI configuration in *Content sources*](../../configure/content-sources.md).
144
+
145
+
Example fragment (only the job — combine with triggers and permissions from the tabs above):
To keep docs in a deployable state, enable required status checks for the **docs-build** workflow. The check name is typically **`docs-build / build`** (workflow name + job id).
99
160
100
161
101
162
102
163
103
164
## Deployments
104
165
105
-
If the `docs-build` workflow is successful, the `docs-deploy` workflow will create a deployment visible in the GitHub UI on your PR.
166
+
After **docs-build** succeeds, **docs-deploy** runs and can create or update a deployment in the GitHub UI for the PR.
If you previously required **`docs-preview / build`** or **`preview-build`**, update branch protection to require **`docs-build`** / **`docs-build / build`** instead.
Copy file name to clipboardExpand all lines: docs/migration/guide/move-ref-docs.md
+55-23Lines changed: 55 additions & 23 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -103,63 +103,95 @@ Example commit: [#398/commit](https://github.com/elastic/apm-agent-android/pull/
103
103
104
104
### Step 3: Add the new CI checks
105
105
106
-
There are two CI checks to add:
106
+
Add three workflow files from [`elastic/docs-actions`](https://github.com/elastic/docs-actions) (`@v1`). Full copy-paste examples and explanations are in [How to set up docs previews](./how-to-set-up-docs-previews.md).
107
107
108
-
**`docs-build.yml`**
109
-
Add a file named `docs-build.yml` at `.github/workflows/docs-build.yml`. The contents of this file are below:
If the documentation you are adding will not live in the `/docs/*` dir of the repository, you must update the `path-pattern` appropriately. Please reach out in #docs-team if you need help with this.
If the documentation you are adding will not live in the `/docs/*` dir of the repository, you must update `path-pattern` on **both** `docs-build` and `docs-deploy` (and adjust `use-release-branches` only if your branching strategy requires it). Please reach out in #docs-team if you need help with this.
190
+
:::
191
+
192
+
:::{note}
193
+
If you only use continuous deployment from `main` (no release-line branches), omit `\d+.\d+` from `push.branches`, remove `use-release-branches`, and drop the matching `with:` from **docs-deploy** — see the minimal examples in [How to set up docs previews](./how-to-set-up-docs-previews.md).
194
+
:::
163
195
164
196
Example PR: [#398](https://github.com/elastic/apm-agent-android/pull/398)
0 commit comments