Design: Sync whats-new.md to feature-web-apps on Change

Date: 2026-04-22 Status: Approved

Overview

A GitHub Actions workflow in cloudzero-documentation that automatically opens a pull request in feature-web-apps whenever docs/Introduction/whats-new.md is updated on the v1.0 branch. The PR copies the file's content (with ReadMe frontmatter stripped) to libs/ui/help-guidance/src/data/whats-new.md in the target repo.

Trigger

• on: push to branch v1.0, path filter docs/Introduction/whats-new.md
• on: workflow_dispatch for manual testing and backfill runs

Workflow File

.github/workflows/sync-whats-new.yml in cloudzero-documentation.

Frontmatter Stripping

docs/Introduction/whats-new.md begins with a YAML block delimited by ---. An awk command skips everything up to and including the second ---, writing only the markdown body to a temp file. No extra tooling required.

awk 'BEGIN{f=0} /^---/{f++; next} f>=2{print}' source.md > stripped.md

Cross-Repo Authentication

Uses actions/create-github-app-token@v1 with secrets CLOUDZERO_GITHUB_ACTIONS_APP_ID and CLOUDZERO_GITHUB_ACTIONS_APP_PRIVATE_KEY, scoped to the feature-web-apps repository. This is the same pattern used in feature-web-apps/publish-knowledge.yml.

Setup requirement: The GitHub App must have contents: write and pull-requests: write permissions on feature-web-apps. Verify this before deploying the workflow.

Sync Steps

1. Checkout cloudzero-documentation to access the source file.
2. Generate a GitHub App token scoped to feature-web-apps.
3. Clone feature-web-apps into a temp directory using the token.
4. Strip frontmatter and write the result to libs/ui/help-guidance/src/data/whats-new.md inside the cloned repo.
5. Diff the working tree — if no changes, exit early with a logged message.
6. Create branch sync/whats-new-<short-sha> (7-char SHA of the triggering commit).
7. Commit: chore: sync whats-new from cloudzero-documentation (<short-sha>).
8. Open a PR against main in feature-web-apps via gh CLI. PR body references the triggering commit URL.

No-Change Guard

If the stripped content is identical to what is already in feature-web-apps, the workflow exits cleanly without creating a branch or PR. This prevents duplicate PRs on re-runs.

Target

Out of Scope

• Merging the PR automatically (human review required).
• Syncing any other documentation files.
• Transforming the markdown content beyond frontmatter removal.