Migrate changelog workflows to unified release-notes reusable workflow

[Mpdreamz]

Replaces the three legacy changelog workflows and the upstream-update script with the unified `release-notes` reusable workflow from `elastic/docs-actions`, and moves changelog bundle creation from the pre-release phase into a post-release job that runs after the GitHub release is cut.

Affects: CI/CD workflows, release process

Prompt summary: Migrate elastic/elastic-otel-java to use the same release-notes workflow strategy as the docs-playground-release-notes-tagged-workflow repo — wire bundle generation inline in release-step-3 after the GITHUB_TOKEN-created release, instead of relying on the on: release event (which GITHUB_TOKEN suppresses) or the old pre-release committed-bundle approach.

Why

The legacy setup had three problems. First, changelog-upload.yml uploaded per-PR entries to the CDN, while changelog-init.yml / changelog-submit.yml handled validation, comments, and auto-committing changelog files separately — three workflows doing what one can. Second, pre-post-release.yml generated the bundle by running docs-builder changelog bundle and committing docs/releases/<version>.yaml into the pre-release branch; the release notes markdown referenced those committed files, which meant the bundle was baked before the release tag existed and couldn't be updated post-facto. Third, bundle-on-release: true in release-notes.yml was dead code because release-step-3.yml creates the GitHub release with GITHUB_TOKEN, and GitHub suppresses the on: release event for GITHUB_TOKEN-created releases.

What

Three old workflows deleted

changelog-init.yml, changelog-submit.yml, and changelog-upload.yml are removed, along with .ci/changelog-upstream-update.sh. Their responsibilities are covered by the new workflows below.

Three new workflows added

release-notes.yml handles validate (on PR), upload (on push to main), and is the trigger that the two downstream workflows listen to. release-notes-comments.yml upserts the changelog preview comment on PRs. release-notes-changelog-file.yml auto-commits a changelog entry file for PRs that are missing one. These two downstream workflows are intentionally kept as separate files so repos can opt into each independently.

Bundle creation moved post-release

release-step-3.yml gains a bundle job (runs bundle-create-version@v1, reads from CDN, no Docker) and a bundle-publish job (OIDC-scoped upload to S3), both chained after create-github-release. The docs-builder/setup@v1 and Generate documentation changelog bundle steps are removed from pre-post-release.yml — the committed docs/releases/*.yaml approach is replaced entirely.

Release notes now CDN-sourced

docs/release-notes/*.md files changed from :::{changelog} /releases/ (local file) to :::{changelog} edot-java (CDN product name). docs/docset.yml gains release_notes: [edot-java] so docs-builder prefetches bundles at startup.

Verify

# confirm the three deleted workflows are gone and release-notes.yml is present
git diff main --name-only
# confirm pre-post-release.yml no longer references docs-builder or changelog bundle
grep -n 'docs-builder\|changelog bundle' .github/workflows/pre-post-release.yml

[v1v]

some nits, to use the same permission strategy where top-level is empty and the ones in the jobs are defined with more granularity

[theletterf]

Hey, I was looking at this and had a couple of questions (happy to be wrong on either).

On the bundle strategy: release-step-3.yml creates the GitHub release with GH_TOKEN: ${{ github.token }}. GitHub doesn't fire on: release for events created by GITHUB_TOKEN, so bundle-on-release: true in release-notes.yml would never trigger. Would it make sense to add the bundle jobs directly inside release-step-3, after the create-github-release step, instead?

On the render pages: the four docs/release-notes/*.md files are now pointing at :::{changelog} edot-java on the CDN, but I don't think any bundles have been published there yet. The old changelog-upload.yml uploaded entries, not release bundles. The build / build check seems to be failing because of a CDN 404 on that. Could those four files (and the release_notes: block in docset.yml) stay on the local path for now, and move to CDN in a follow-up once the first bundle is published?

[github-actions]

🔍 Preview links for changed docs

• docs/release-notes/breaking-changes.md
• docs/release-notes/deprecations.md
• docs/release-notes/index.md
• docs/release-notes/known-issues.md

[github-actions]

✅ Elastic Docs Style Checker (Vale)

No issues found on modified lines!

---

The Vale linter checks documentation changes against the Elastic Docs style guide. To use Vale locally or report issues, refer to Elastic style guide for Vale.

[SylvainJuge]

do you think we could simplify and only have one workflow for both "comment" or "pushing the changelog file" when relevant ? It's quite likely to be replicated across repositories so having a single top-level GH action would make this simpler and avoid duplication.

Here they have the same run triggers and the same permissions on the PR.

[Mpdreamz]

Keeping them separate is intentional — the onboarding guide documents these as two distinct files to copy, and repos can opt into either one independently (comments without auto-commit, or vice versa). I merged them in a previous commit and then reverted it; sorry for the noise, that was Claude being too eager.

[Mpdreamz]

Also both are completely optional if you want neither comments or automated PR checkins, this limits blast radius a bit for repos that just want PR checks bundle automation.

[SylvainJuge]

To implement #1238 would it be just a matter of modifying the bundle file just between those two steps ? Or is it something we would need to do on a separate workflow ?

[Mpdreamz]

The plan is to add a description input to elastic/docs-actions/changelog/bundle-create-version@v1 itself, then wire the output of .ci/changelog-bundle-description.sh into it here in release-step-3.yml. That keeps the description logic in this repo and avoids rebuilding it inside the action. Tracked in #1238.

[Mpdreamz]

Done — elastic/docs-actions#367 adds a description input to bundle-create-version@v1, and this PR now runs .ci/changelog-bundle-description.sh before Create bundle and passes its output as that input. Ties off the last item from the old pre-release bundle step.

[SylvainJuge]

Is it only checking the PR has a changelog file and/or the appropriate labels are applied here ?

[Mpdreamz]

On a PR event it always validates labels, checks whether a changelog file is present (if the labels and workflow config require one), and if a file is present validates its name format and contents. On push to main it uploads the merged PR's changelog entry to the CDN. Bundle creation is separate, handled by bundle-create-version@v1 in release-step-3.yml after the GitHub release is cut.