feat: add release automation

[shubham-sumo]

Description

Adds end-to-end GitHub Actions automation for detecting, preparing, building, and publishing Java, NodeJS, and Python Lambda layer releases. Only the final release promotion remains manual.

---

Complete release flow

Weekly cron / manual dispatch
        │
        ▼
┌─────────────────────────────┐
│  Check Upstream Releases    │  Detects newer upstream OTel Lambda tags
└─────────────┬───────────────┘
              │ dispatches
              ▼
┌─────────────────────────────┐
│  Release Prepare            │  Pins submodule, generates metadata, opens PR
└─────────────┬───────────────┘
              │ human merges
              ▼
┌─────────────────────────────┐
│  Release Tag                │  Assembles changelog, creates tag, pushes
└─────────────┬───────────────┘
              │ dispatches at tag
              ▼
┌─────────────────────────────┐
│  Release Build - <language> │  Builds artifacts, publishes layers, creates pre-release
└─────────────┬───────────────┘
              │ human reviews
              ▼
┌─────────────────────────────┐
│  Manual promotion           │  Promote pre-release → latest via GitHub UI
└─────────────────────────────┘

---

What this PR adds

Upstream release detection

• Weekly Check Upstream Releases workflow (also manually dispatchable).
• Dry-run mode and optional per-language filter for safe testing.
• Detects the latest language-specific upstream tag (layer-javaagent/*, layer-nodejs/*, layer-python/*).
• Compares with upstream_release_tag in <language>/version.txt.
• Computes the next Sumo Logic minor version and dispatches Release Prepare.
• Skips languages with an existing open prepare PR.

Release preparation

• Validates version format and language-specific upstream tag prefix.
• Verifies the upstream tag actually exists on the remote.
• Rejects duplicate tags or branches.
• Pins opentelemetry-lambda submodule to the selected upstream release tag.
• Captures the resolved commit SHA for auditability in the PR description.
• Derives SDK, instrumentation, and Collector versions from the pinned submodule.
• Updates <language>/version.txt, layer-data.sh, sample-apps/template.yaml, <language>/README.md, root README.md, and creates changelog/<language>-v<version>.md.
• Opens prepare-<language>-v<version> PR with checklist and provenance.
• One concurrency group per language allows concurrent Java/NodeJS/Python preparation.

Changelog assembly and release tagging

• Per-release changelog fragments avoid direct CHANGELOG.md editing across concurrent PRs.
• On merge, Release Tag inserts the fragment into CHANGELOG.md, removes the fragment via git rm, commits, creates an annotated tag, and atomically pushes main + tag.
• Serialized with a global release-tag-main concurrency group.

Automatic release build dispatch

• After pushing the tag, Release Tag explicitly dispatches release-build-<language>.yml at that tag ref.
• Explicit dispatch is required because GITHUB_TOKEN tag pushes do not trigger downstream push-triggered workflows.
• Each release-build workflow now accepts workflow_dispatch alongside its existing tag-push trigger.
• A validate-ref guard job rejects accidental dispatch from non-tag refs (prevents broken artifacts/releases if someone clicks "Run workflow" on main).
• The build workflow creates artifacts, publishes Lambda layers to all regions, and creates a GitHub pre-release with ARN tables.

Release finalization (manual)

• Release Finalize is available via manual dispatch only.
• Creates a release-<tag> branch from the tag commit (not from main).
• Updates the language README title on that branch.

---

What does not happen automatically

What	Why
Changelog content authoring	A reviewer must replace the TODO in the fragment before merge
Conflict resolution between concurrent PRs	Root README and submodule gitlink conflicts require manual resolution
Release Finalize	Only available via manual dispatch; not part of the automated flow
Release branch creation	Use Release Finalize if a release-<tag> branch is needed
Pre-release → latest promotion	A human must review and promote via the GitHub Releases UI

---

Automated-flow simulation (Python example)

Starting state: python/version.txt has current_version=1.40.0 and upstream_release_tag=layer-python/0.19.0. Upstream publishes layer-python/0.20.0.

#	Stage	What happens
1	Detect	Weekly cron (or manual with dry_run=false) finds layer-python/0.20.0 > layer-python/0.19.0, computes next version 1.41.0
2	Prepare	Dispatches Release Prepare with language=python, version=1.41.0, otel_lambda_tag=layer-python/0.20.0
3	Pin submodule	Checks out opentelemetry-lambda at layer-python/0.20.0, captures SHA (e.g. 247d46c7...)
4	Generate files	ci/release-prepare.sh updates metadata, layer data, template, READMEs, creates changelog/python-v1.41.0.md
5	Open PR	prepare-python-v1.41.0 opens with upstream tag/SHA provenance and pre-merge checklist
6	Review	Human fills in changelog, verifies versions and submodule, merges
7	Assemble changelog	Release Tag inserts fragment into CHANGELOG.md, removes fragment
8	Create tag	Commits changelog, creates annotated python-v1.41.0, pushes main + tag atomically
9	Dispatch build	Release Tag runs gh workflow run release-build-python.yml --ref python-v1.41.0
10	Build & publish	Artifacts built, Lambda layers published to all regions, GitHub pre-release created
11	Promote	Human reviews pre-release, promotes to latest release via GitHub UI

Safe dry-run test:

Check Upstream Releases → dry_run: true, language: python

Reports what would be dispatched without creating branches or PRs.

---

File reference

Workflows

File	Purpose
.github/workflows/release-check-upstream.yml	Weekly/manual detection of newer upstream OTel Lambda releases; dispatches Release Prepare
.github/workflows/release-prepare.yml	Pins submodule, runs prepare script, opens the release preparation PR
.github/workflows/release-tag.yml	Post-merge: assembles changelog, creates tag, pushes, dispatches build
.github/workflows/release-build-java.yml	Builds Java layer, publishes to AWS, creates GitHub pre-release (added: workflow_dispatch + validate-ref)
.github/workflows/release-build-nodejs.yml	Builds NodeJS layer, publishes to AWS, creates GitHub pre-release (added: workflow_dispatch + validate-ref)
.github/workflows/release-build-python.yml	Builds Python layer, publishes to AWS, creates GitHub pre-release (added: workflow_dispatch + validate-ref)
.github/workflows/release-finalize.yml	Manual: creates release-<tag> branch from tag and updates language README title

Scripts

File	Purpose
ci/release-prepare.sh	Creates changelog fragment; updates version.txt, layer-data.sh, template.yaml, language README title, root README component versions
ci/release-finalize.sh	Updates language README title (used by Release Finalize workflow)

Metadata

File	Purpose
java/version.txt	Tracks Java release version and last-processed upstream tag
nodejs/version.txt	Tracks NodeJS release version and last-processed upstream tag
python/version.txt	Tracks Python release version and last-processed upstream tag
changelog/.gitkeep	Ensures the changelog/ directory exists in fresh clones

Documentation

File	Purpose
docs/release.md	Full releasing guide: metadata, preparation, post-merge flow, recovery, promotion

---

Changes to existing release-build workflows

• Added workflow_dispatch trigger (no inputs — the tag is the dispatch ref).
• Added validate-ref guard job that fails fast if GITHUB_REF_NAME doesn't match the expected <language>-vX.Y.Z pattern.
• No changes to build steps, artifact naming, layer publication, or pre-release creation logic.

---

Testing

• Validated all workflow YAML parses correctly.
• Exercised prepare PR generation for Java, NodeJS, and Python in the fork.
• Verified generated PRs update per-language metadata and release files.
• Verified submodule pin resolves to the SHA shown in the generated PR.
• Verified validate-ref rejects dispatch from branch refs.
• Verified concurrent preparation limited to one open PR per language.

Documentation

Updated docs/release.md covering: release metadata format, prepare-PR contents and checklist, submodule provenance, concurrent-PR conflict handling, automatic post-merge flow (changelog → tag → dispatch → build → pre-release), recovery (retry build via dispatch at existing tag), and manual promotion.

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.

[Copilot]

Pull request overview

Adds GitHub Actions–based release automation to detect upstream OpenTelemetry Lambda layer releases and generate human-reviewable “prepare” PRs, then (post-merge) assemble changelog fragments, create annotated tags, and explicitly dispatch the existing release-build workflows.

Changes:

• Introduces upstream release detection (release-check-upstream.yml) and release preparation (release-prepare.yml) automation, plus supporting scripts.
• Adds post-merge changelog assembly + tag creation workflow (release-tag.yml) and a manual “finalize” workflow (release-finalize.yml) for optional release branches.
• Adds per-language version.txt release state and updates release documentation; enables manual dispatch for existing release-build workflows with ref validation.

Reviewed changes

Copilot reviewed 13 out of 14 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
python/version.txt	Adds Python release state (current_version, upstream_release_tag) consumed by automation.
nodejs/version.txt	Adds NodeJS release state consumed by automation.
java/version.txt	Adds Java release state consumed by automation.
docs/release.md	Replaces the manual release guide with the new automated+manual hybrid procedure.
ci/release-prepare.sh	Generates changelog fragments and updates per-language + root release metadata based on pinned upstream submodule.
ci/release-finalize.sh	Updates language README title for an optional release-<tag> branch flow.
changelog/.gitkeep	Keeps the changelog/ directory present for fragment-based workflow.
.github/workflows/release-tag.yml	Post-merge: assembles fragment into CHANGELOG.md, deletes fragment, creates annotated tag, dispatches release build.
.github/workflows/release-prepare.yml	Manual-dispatch workflow to pin upstream submodule, run prepare script, and open a “prepare” PR.
.github/workflows/release-finalize.yml	Manual-dispatch workflow to create a release-<tag> branch and update README title (recovery/support flow).
.github/workflows/release-check-upstream.yml	Scheduled/manual upstream tag detection that can dispatch release-prepare when new releases are found.
.github/workflows/release-build-python.yml	Adds workflow_dispatch support with tag-ref validation gate.
.github/workflows/release-build-nodejs.yml	Adds workflow_dispatch support with tag-ref validation gate.
.github/workflows/release-build-java.yml	Adds workflow_dispatch support with tag-ref validation gate.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.