feat: v2 workflows

[melissag-ensemble]

Description

Reintroduces #23 (previously reverted in #25 because the in-place rewrite broke v1 callers). Ships the changes as versioned files (*-v2.yml) alongside v1, so content repos can opt into v2 on their own schedule.

Ticket

https://jira.corp.adobe.com/browse/DEVSITE-2292

Related PRs

• feat: v2 private workflows AdobeDocsPrivate/adp-devsite-workflow-private#1
• feat: v2 buildContributors adp-devsite-utils#75
• feat: v2 workflows dev-docs-template#48

Test branches

• https://github.com/AdobeDocs/adp-devsite-workflow/tree/test-v2-workflows
• https://github.com/AdobeDocs/adp-devsite-utils/tree/v2-workflows
• https://github.com/AdobeDocs/adp-devsite-branch-protection-test
• https://github.com/AdobeDocsPrivate/adp-dev-docs-private

Tests

Setup (testing artifact only): For this validation pass, the test repos adp-devsite-branch-protection-test and adp-dev-docs-private have both v1 and v2 workflows installed so v1 regression and v2 can be exercised side-by-side. A normal content repo ships only one set. Because push: main triggers both deploy.yml and deploy-v2.yml in parallel, disable the set you're not testing via Actions → workflow → kebab menu → Disable workflow:

• Phases 1-5 (v2 testing): disable v1 (deploy.yml, stage.yml, build-auto-generated-files.yml)
• Phase 6 (v1 testing): disable v2 (deploy-v2.yml, stage-v2.yml, build-auto-generated-files-v2.yml)

Once all phases pass, delete the v1 workflows from these test repos so they converge on v2.

Phase 0 — Local dev

#	Action	Steps	Repo Config	Expected	Screenshots
T00	npm run dev (public repo)	1. Checkout adp-devsite-branch-protection-test 2. Run npm run dev	AdobeDocs repo (public); buildContributors routes to buildContributorsV2 from adp-devsite-utils#v2-workflows	Dev server starts on port 3003; contributors.json + adp-site-metadata.json generated locally; no API auth errors
T00b	npm run dev (private repo)	1. Checkout adp-dev-docs-private 2. Run npm run dev	AdobeDocsPrivate repo (private)	Dev server starts on port 3003; contributors.json + adp-site-metadata.json generated locally

Phase 1 — v2, no branch protection

Repo: adp-devsite-branch-protection-test (AdobeDocs, public). Both deploy-v2.yml and build-auto-generated-files-v2.yml use secrets: inherit — Phase 1 therefore validates the inherit pattern end-to-end.

#	Action	Steps	Repo Config	Expected	Screenshots
T01	Push to main with markdown changes	1. Edit a .md file in src/pages/ 2. Commit and push to main	v2 workflows, no branch protection, app secrets set, secrets: inherit	• All jobs green • echo-state: Has App Secrets = true, Deploy to prod = true, Deploy to stage = false • Bot commits: chore: auto-generate contributors + chore: auto-generate site metadata • Prod deploy steps ran • Deploy processes ONLY the user-pushed .md (not the bot's contributors.json/adp-site-metadata.json) — verifies sha: head_sha filter on changed-files	https://github.com/AdobeDocs/adp-devsite-branch-protection-test/actions/runs/25404165681/job/74511084108
T02	Verify bot commit does NOT trigger deploy re-run	1. After T01 completes, check Actions tab for a second run triggered by the bot's auto-generate commits	same	No new run triggered (if: github.actor != 'adp-devsite-app[bot]' guard on the deployment job blocks bot-triggered deploys)
T03	workflow_dispatch, baseSha provided, deployAll unchecked	1. Actions → deploy workflow → Run workflow 2. Enter a SHA from a few commits back in baseSha 3. Leave deployAll unchecked 4. Run	same	Base Sha in echo-state matches provided value; delta build runs from that SHA	https://github.com/AdobeDocs/adp-devsite-branch-protection-test/actions/runs/25411792585/job/74534981847 (note: npm warn deprecated glob@10.5.0 warnings may appear in build-contributors log - known issue, DEVSITE-2381)
T04	workflow_dispatch, deployAll checked	1. Actions → deploy workflow → Run workflow 2. Leave baseSha empty, check deployAll 3. Run	same	Deploy All = true in echo-state; full rebuild runs (--all); all src/pages/ files deployed	https://github.com/AdobeDocs/adp-devsite-branch-protection-test/actions/runs/25412587753/job/74537378469
T04b	workflow_dispatch, env: stage & prod	1. Actions → deploy workflow → Run workflow 2. Select env: stage & prod 3. Enter a SHA from a few commits back in baseSha (leaving it empty triggers a known changed-files shallow-clone bug - tracked in DEVSITE-2379) 4. Leave deployAll unchecked 5. Run	same	• echo-state: Deploy to stage = true, Deploy to prod = true (both flags set via contains(inputs.env, ...)) • Stage steps ran (preview + cache-bust) • Prod 2-step deploy ran (preview → sleep → live) • Both stage and prod environments updated in a single run	https://github.com/AdobeDocs/adp-devsite-branch-protection-test/actions/runs/25414729038/job/74543758992

Phase 1b — Fork PR (core DEVSITE-2292 scenario)

V2 fixes fork PR failures by removing pull_request from build-auto-generated-files-v2.yml (auto-gen now only runs at deploy time, called via workflow_call from the deploy workflow). The linter bot also moved to a workflow_run trigger so it can comment on fork PRs without needing fork-side write access. These tests verify the PR-time experience is clean for both forks and internal branches.

#	Action	Steps	Repo Config	Expected	Screenshots
T05	Fork PR with src/pages changes	1. Fork adp-devsite-branch-protection-test 2. Edit a .md file in src/pages/ 3. Open a PR against main	v2 workflows, no branch protection, app secrets set	• Lint check runs • Build Auto-Generated Files check NOT present (v2 build-auto-generated-files-v2.yml has no pull_request trigger) • No secrets-related failures • If lint warnings found: Post Linter Report bot posts a comment — confirms workflow_run-based posting works cross-fork	AdobeDocs/adp-devsite-branch-protection-test#52

Phase 2 — Branch protection

#	Action	Steps	Repo Config	Expected	Screenshots
T06	Merge PR (App IS bypass actor)	1. Confirm ADP DevSite App is set as bypass actor in ruleset 2. Create a feature branch, edit a .md file in src/pages/ 3. Open a PR against main and merge it	Branch protection enabled, App is bypass actor (adp-devsite-branch-protection-test)	Merge triggers deploy workflow; build-auto-generated-files succeeds (bot's app-token push allowed by App's bypass); bot commit in history; deploy completes	https://github.com/AdobeDocs/adp-devsite-branch-protection-test/actions/runs/25447848572/job/74656816407
T07	Merge PR (App NOT bypass actor)	1. Remove ADP DevSite App from bypass actors 2. Create a feature branch, edit a .md file in src/pages/ 3. Open a PR against main and merge it	Branch protection enabled, App is NOT bypass actor	• build-contributors fails on git push (push rejected — App lacks bypass) • build-site-metadata still runs (not skipped — if: always()) and also fails on git push — confirms needs: build-contributors + if: always() chain • deploy still runs (if: always()) and deploys the user's merge commit (no auto-gen file updates in branch)	https://github.com/AdobeDocs/adp-devsite-branch-protection-test/actions/runs/25448780351/job/74660163050

Phase 3 — No app secrets

Setup: Disable branch protection if it was left on from Phase 2 — Phase 3 reuses Phase 1's setup (no protection) so a direct push to main can trigger the workflow.

#	Action	Steps	Repo Config	Expected	Screenshots
T08	Push to main	1. Temporarily remove or unset ADP_DEVSITE_APP_ID repo secret 2. Push a markdown change to main	v2 workflows, ADP_DEVSITE_APP_ID not set	Has App Secrets = false in echo-state; build-auto-generated-files skipped; deploy completes successfully	https://github.com/AdobeDocs/adp-devsite-branch-protection-test/actions/runs/25455183726/job/74682627646

Phase 4 — AdobeDocsPrivate cross-org

adp-dev-docs-private routes through AdobeDocsPrivate/adp-devsite-workflow-private/.github/workflows/deploy-v2.yml@v2-workflows — a parallel implementation that always full-rebuilds, deploys to Azure (not AEM), explicitly copies static/, and doesn't auto-gen on push. Build-auto-gen uses explicit secret passing (free-plan AdobeDocsPrivate constraint); deploy uses secrets: inherit.

#	Action	Steps	Repo Config	Expected	Screenshots
T09	workflow_dispatch (env=prod)	1. Actions → deploy workflow → Run workflow on test-v2-workflows branch 2. Leave env as default (prod)	AdobeDocsPrivate repo (adp-dev-docs-private), app secrets set as repo-level secrets	• Jobs run: matrix_prep → set-state → echo-state → pre-build → build • echo-state: Deploy to prod = true, Deploy to stg = false, Repository org = AdobeDocsPrivate, Path prefix populated from config.md • build job: full site rebuilt, static assets copied, Azure deploy completed against prod connection string, Fastly cache purged using AIO_FASTLY_PROD_URL	https://github.com/AdobeDocsPrivate/adp-dev-docs-private/actions/runs/25462819921/job/74709206897
T09b	workflow_dispatch via stage-v2.yml	1. Actions → Staging workflow → Run workflow on test-v2-workflows branch	same as T09	• echo-state: Deploy to stg = true, Deploy to prod = false • build job runs full rebuild • "Select Connection String" step picks AIO_AZURE_DEV_PRIVATE_CONNECTION_STRING (stage) • Azure deploy targets stage (dev) Blob Storage • Fastly purge uses AIO_FASTLY_DEV_URL	https://github.com/AdobeDocsPrivate/adp-dev-docs-private/actions/runs/25463110394/job/74710678289
T09c	Push static/ file to main	1. Edit a file under static/ in adp-dev-docs-private (e.g. static/foo.json) 2. Commit and push to main	same as T09	• build job runs full rebuild (private workflow has no changed-files filter) • "Copy spec, data, and static media files" step copies static/foo.json into _site/{pathPrefix}/static/foo.json (preserves static/ prefix) • Deployed to Azure at {pathPrefix}/static/foo.json • File accessible via runtime connector at developer-stage.adobe.com/{pathPrefix}/static/foo.json (private repos serve static via runtime connector; public repos fetch via raw GitHub instead)	https://github.com/AdobeDocsPrivate/adp-dev-docs-private/actions/runs/25463910593/job/74712749260

Phase 5 — Staging (stage-v2.yml)

#	Action	Steps	Repo Config	Expected	Screenshots
T10	workflow_dispatch via stage-v2.yml, no baseSha	1. Actions → Staging workflow → Run workflow from main branch of adp-devsite-branch-protection-test (caller calls shared workflow at @test-v2-workflows) 2. Leave baseSha empty, leave deployAll unchecked 3. Run	v2 workflows, app secrets set	Deploy to stage = true, Deploy to prod = false in echo-state; Base Sha from last successful stage-v2.yml run (independent of deploy baseline); auto-gen runs; stage deploy completes	https://github.com/AdobeDocs/adp-devsite-branch-protection-test/actions/runs/25463240032/job/74710433434

Phase 6 — v1 workflows

Regression coverage — verifies that v2 changes to adp-devsite-utils (new buildContributorsV2 function) and shared workflow restructuring don't break v1 callers still on the unchanged code paths.

#	Action	Steps	Repo Config	Expected	Screenshots
T11	npm run dev (old)	1. Checkout any v1 content repo on main 2. Run npm run dev	Any v1 repo on main	Dev server starts normally	https://github.com/AdobeDocs/adp-devsite-branch-protection-test/actions/runs/25463240032/job/74710433434