Release 1.27.0 → main (production)

.claude/skills/tutorial-qa-to-prod/SKILL.md

@@ -0,0 +1,175 @@
+---
+name: tutorial-qa-to-prod
+description: Use when a tutorial author has previewed a tutorial in the QA channel (/tutorials-qa/) and wants to promote it to PROD — copies the tutorial markdown from the private sap-tutorials/<product>-Contribution repo (QA source) to the canonical public sap-tutorials/Tutorials repo (PROD source) and opens a PR in each, cross-linked. Triggers on "promote this tutorial to prod", "copy from QA to PROD", "publish my QA tutorial", "move <slug> from Contribution to Tutorials".
+---
+
+# Promote a tutorial from QA (Contribution) to PROD (canonical Tutorials)
+
+An author edits and previews a tutorial in its product-specific
+**`sap-tutorials/<product>-Contribution`** repo, served on the platform's QA
+channel at `/tutorials-qa/<slug>`. Promoting it to PROD means landing the same
+markdown in the **canonical public repo `sap-tutorials/Tutorials`** at the same
+`tutorials/<slug>/<slug>.md` path. Merging the `Tutorials` PR is what the PROD
+content rebuild consumes — the platform auto-discovers `Tutorials` content and
+republishes to the PROD HANA BLOBs.
+
+The two repos share **no git fork network**, so one cross-repo PR is impossible.
+This skill copies the file once and opens **one PR in each repo**, cross-linked.
+
+## Non-negotiable facts (verified 2026-09-15)
+
+- **Host is `github.com`, NOT `github.tools.sap`.** Always `export GH_HOST=github.com`.
+- **Default branches DIFFER per repo — never hardcode.**
+  - Canonical `sap-tutorials/Tutorials` (PROD) → **`master`**.
+  - `sap-tutorials/<product>-Contribution` (QA) → **`main`**.
+  - Resolve each repo's default with the API (Step 0); do not assume.
+- **`*-Contribution` repos are private** → `raw.githubusercontent.com` 404s.
+  Verify pushed content via the authenticated contents API, not raw curl.
+- **Path parity.** Both repos use `tutorials/<slug>/<slug>.md`. Same slug → same path.
+- **First promotion is a CREATE, not an update.** A QA-only tutorial does NOT
+  exist in `Tutorials` yet (contents API returns 404). Handle create vs update.
+- **No `tutorials-ims` code change is needed.** The platform auto-discovers any
+  org repo with a `tutorials/` folder; merging the `Tutorials` PR triggers PROD.
+
+## Workflow
+
+Work through the GitHub contents API (`gh api`) — do NOT clone `Tutorials`; it is
+huge. Use `$CLAUDE_JOB_DIR/tmp` or a scratch dir for the file. Set
+`export GH_HOST=github.com` first.
+
+### Step 0 — Resolve inputs and per-repo default branches
+
+Identify the QA repo (`sap-tutorials/<product>-Contribution`), the slug, and the
+path `tutorials/<slug>/<slug>.md`. Then resolve BOTH default branches — do not
+assume:
+
+```bash
+export GH_HOST=github.com
+CONTRIB=sap-tutorials/<product>-Contribution
+MAIN=sap-tutorials/Tutorials
+PATHREL="tutorials/<slug>/<slug>.md"
+
+CONTRIB_DEF=$(gh api "repos/$CONTRIB" --jq '.default_branch')   # expect: main
+MAIN_DEF=$(gh api "repos/$MAIN"    --jq '.default_branch')      # expect: master
+```
+
+### Step 1 — Fetch the QA source (source of truth for the copy)
+
+The QA file is what the author previewed and approved — it is authoritative.
+
+```bash
+CONTRIB_SHA=$(gh api "repos/$CONTRIB/contents/$PATHREL?ref=$CONTRIB_DEF" --jq '.sha')
+gh api "repos/$CONTRIB/contents/$PATHREL?ref=$CONTRIB_DEF" --jq '.content' | base64 -d > file.md
+```
+
+If this 404s, the slug/path is wrong — re-confirm with the author. Do NOT invent content.
+
+### Step 2 — Determine PROD state: CREATE or UPDATE (+ drift guard)
+
+```bash
+if MAIN_SHA=$(gh api "repos/$MAIN/contents/$PATHREL?ref=$MAIN_DEF" --jq '.sha' 2>/dev/null); then
+  MODE=update
+else
+  MODE=create   # QA-only tutorial, first promotion — no sha, no drift check
+fi
+```
+
+- **MODE=create** → nothing in PROD to clobber. Proceed; the contents PUT omits `sha`.
+- **MODE=update** → PROD already has this tutorial. **DRIFT GUARD:** diff the
+  current PROD file against the QA file you fetched. If PROD has content the QA
+  copy would silently discard (someone edited PROD directly, or the repos have
+  drifted), **STOP and show the author the diff** before overwriting:
+
+  ```bash
+  gh api "repos/$MAIN/contents/$PATHREL?ref=$MAIN_DEF" --jq '.content' | base64 -d > prod-current.md
+  diff prod-current.md file.md && echo "IN SYNC (no-op)" || echo "DRIFT — review below before promoting"
+  ```
+
+  If `diff` is empty, the promotion is a no-op — tell the author PROD already
+  matches QA; don't open an empty PR. If it differs, that's the expected
+  promotion delta — but confirm the diff is only the author's intended change,
+  not an unrelated PROD edit being reverted.
+
+### Step 3 — For EACH repo, branch + commit the copied file
+
+Same branch name in both (e.g. `promote/<slug>-to-prod`). QA repo commits the
+same content back to itself on a branch (so the promotion is auditable there
+too); PROD repo receives the copy. Use each repo's OWN default branch as base
+and each repo's OWN current file sha.
+
+```bash
+promote_to() {   # $1=repo  $2=default-branch  $3=current-file-sha-or-empty
+  local REPO="$1" DEF="$2" CUR_SHA="$3" BR="promote/<slug>-to-prod"
+  local BASE_SHA; BASE_SHA=$(gh api "repos/$REPO/git/ref/heads/$DEF" --jq '.object.sha')
+  gh api "repos/$REPO/git/refs" -f ref="refs/heads/$BR" -f sha="$BASE_SHA" >/dev/null
+
+  local B64; B64=$(base64 -w0 file.md)
+  if [ -n "$CUR_SHA" ]; then
+    printf '{"message":"docs(%s): promote to PROD","branch":"%s","sha":"%s","content":"%s"}' \
+      "<slug>" "$BR" "$CUR_SHA" "$B64" > payload.json
+  else
+    printf '{"message":"docs(%s): promote to PROD","branch":"%s","content":"%s"}' \
+      "<slug>" "$BR" "$B64" > payload.json
+  fi
+  gh api -X PUT "repos/$REPO/contents/$PATHREL" --input payload.json --jq '.commit.sha'
+
+  # verify byte-for-byte (works on private repos)
+  gh api "repos/$REPO/contents/$PATHREL?ref=$BR" --jq '.content' | base64 -d > pushed.md
+  diff file.md pushed.md && echo "MATCH ($REPO)" || { echo "MISMATCH ($REPO) — STOP"; return 1; }
+}
+
+promote_to "$CONTRIB" "$CONTRIB_DEF" "$CONTRIB_SHA"           # QA branch (audit)
+promote_to "$MAIN"    "$MAIN_DEF"    "${MAIN_SHA:-}"          # PROD copy (empty sha => create)
+```
+
+Do not open a PR for a repo until its `promote_to` printed `MATCH`.
+
+### Step 4 — Open a PR in each repo, cross-linked
+
+```bash
+# PROD first (the one that matters), base = its OWN default branch
+PROD_PR=$(gh pr create --repo "$MAIN" --base "$MAIN_DEF" --head promote/<slug>-to-prod \
+  --title "Promote <slug> to PROD" \
+  --body "Promotes QA-previewed tutorial \`<slug>\` to PROD. Paired QA PR: <fill after>. Merging this triggers the PROD content rebuild." )
+
+QA_PR=$(gh pr create --repo "$CONTRIB" --base "$CONTRIB_DEF" --head promote/<slug>-to-prod \
+  --title "Promote <slug> to PROD (QA-side record)" \
+  --body "QA-side record of promoting \`<slug>\`. Paired PROD PR: $PROD_PR" )
+
+gh pr edit "$PROD_PR" --body "Promotes QA-previewed tutorial \`<slug>\` to PROD. Paired QA PR: $QA_PR. Merging this triggers the PROD content rebuild."
+```
+
+### Step 5 — Report
+
+Report **both PR URLs**, whether it was a CREATE or UPDATE, and that content was
+verified identical in both. Remind the author: **merging the `Tutorials` (PROD)
+PR is what publishes to PROD** — the QA-side PR is an audit record.
+
+## Guardrails
+
+- **Never hardcode a base branch.** Resolve each repo's default (Step 0);
+  `Tutorials`=`master`, `-Contribution`=`main` today, but always resolve live.
+- **Never open one PR expecting it to span both repos** — always two.
+- **UPDATE mode: run the drift guard before overwriting PROD.** An empty diff is
+  a no-op (don't open a PR); a diff must be confirmed as only the intended change.
+- **Before adding a follow-up commit to an existing PR branch, check PR state**
+  (`gh pr view <n> --repo <r> --json state,mergedAt`). If MERGED/CLOSED, branch
+  fresh and open a NEW PR — a PUT to a merged PR's branch SUCCEEDS but never
+  reaches the default branch. Confirm changes landed by reading the file at the
+  default-branch ref.
+- **Never `git push`/force-push; never target a non-default base branch.**
+- **QA is the source of truth for the copy** — the author previewed it there.
+  Do not hand-edit content during promotion; if the content is wrong, fix it in
+  the Contribution repo first (see `sap-tutorial-dual-pr` for editing flows),
+  then promote.
+- This skill promotes ONE tutorial (one slug) per run. For a batch, loop the
+  slug and open one PR pair per slug, or ask the author to confirm a multi-slug
+  scope explicitly.
+
+## Relationship to `sap-tutorial-dual-pr`
+
+`sap-tutorial-dual-pr` **edits** a tutorial and mirrors the edit to both repos in
+lockstep (keeping QA and PROD identical after an edit). This skill **promotes** a
+QA-previewed tutorial to PROD (the QA→PROD direction, create-or-update, with a
+drift guard for the first-promotion 404 case). Use dual-pr to change content;
+use this to ship a QA-approved tutorial to PROD.

.deploy/mta.yaml

@@ -10,7 +10,7 @@ ID: tutorials-ims
 # Bump this on each release you deploy — it's the version shown by `cf mtas`
 # and in the mtar filename (tutorials-ims_<version>.mtar). Deploy is manual:
 # `cd .deploy && mbt build && cf deploy mta_archives/tutorials-ims_<version>.mtar -e ../deploy/<env>.mtaext -f`.
-version: 1.26.0
+version: 1.27.0
 
 # Top-level parameters (overridable per-env via deploy/<env>.mtaext).
 parameters:

.github/actions/report-rebuild-failure/action.yml

@@ -14,6 +14,24 @@ inputs:
   channel:
     description: 'Rebuild channel/env used to dedup issues (e.g. "qa", "prod", "dev").'
     required: true
+  repo:
+    description: >-
+      Repository to file/find/close the issue in (owner/name). Defaults to the
+      repo running the workflow. Set to a source `-Contribution` repo to file a
+      per-tutorial author issue there (requires the token to have issues:write
+      on that repo — the tutorials GitHub App with Issues:RW, not the default
+      job GITHUB_TOKEN, which is scoped to the running repo only).
+    required: false
+    default: ${{ github.repository }}
+  slug:
+    description: >-
+      Optional tutorial slug. When set, the issue is per-tutorial (its own
+      dedup marker + title) rather than the channel-level aggregate. Used for
+      author content errors (missing/misnamed source file) so each tutorial
+      gets its own issue in its source repo, assigned to / @-mentioning the
+      author. Empty (default) keeps the channel-aggregate behavior (#1373).
+    required: false
+    default: ''
   run-url:
     description: 'Link to the failing (or succeeding) Actions run.'
     required: true
@@ -48,9 +66,10 @@ runs:
       shell: bash
       env:
         GH_TOKEN: ${{ inputs.github-token }}
-        REPO: ${{ github.repository }}
+        REPO: ${{ inputs.repo }}
         OUTCOME: ${{ inputs.outcome }}
         CHANNEL: ${{ inputs.channel }}
+        SLUG: ${{ inputs.slug }}
         RUN_URL: ${{ inputs.run-url }}
         TRIGGER: ${{ inputs.trigger }}
         DETAILS: ${{ inputs.details }}
@@ -60,14 +79,23 @@ runs:
       run: |
         set -uo pipefail
 
-        # Stable per-channel marker so we find the same issue across runs
-        # without depending on the exact title text.
-        MARKER="<!-- rebuild-failure-marker channel=${CHANNEL} -->"
+        # Stable dedup marker so we find the same issue across runs without
+        # depending on the exact title text. Channel-level by default; when a
+        # SLUG is given it becomes per-tutorial (a slug-scoped marker + title)
+        # so each author content error gets its own deduplicated issue in its
+        # source repo instead of collapsing onto the channel aggregate.
+        if [ -n "$SLUG" ]; then
+          MARKER="<!-- rebuild-failure-marker channel=${CHANNEL} slug=${SLUG} -->"
+          ISSUE_TITLE="🚨 tutorial source error: ${SLUG} (${CHANNEL})"
+        else
+          MARKER="<!-- rebuild-failure-marker channel=${CHANNEL} -->"
+          ISSUE_TITLE="🚨 ${CHANNEL} content rebuild failing"
+        fi
         ESCALATED_LABEL="rebuild-failure-escalated"
 
-        # Locate an existing OPEN failure issue for this channel. Search by the
-        # dedup label, then match the hidden marker in the body so per-channel
-        # issues never collide (qa vs prod). --search keeps the marker literal.
+        # Locate an existing OPEN failure issue for this channel (and slug, when
+        # set). Search by the dedup label, then match the hidden marker in the
+        # body so per-channel / per-tutorial issues never collide.
         find_open_issue() {
           gh issue list --repo "$REPO" --state open --label "$LABEL" \
             --json number,body --limit 50 \
@@ -110,22 +138,52 @@ runs:
         [ -n "$DETAILS" ] && DETAIL_LINE="- **Detail:** ${DETAILS}"
 
         if [ -z "$ISSUE_NUM" ]; then
-          # First failure of a new streak — create the issue. Assignment is what
-          # triggers GitHub's native email to the on-call owner. Build the body
-          # with a single printf (no heredoc — an unindented heredoc breaks the
-          # YAML block scalar; and per-line $(printf) would have its trailing
-          # newlines stripped by command substitution, collapsing the layout).
+          # First failure of a new streak — create the issue, then assign in a
+          # SEPARATE step. Assignment is what triggers GitHub's native email,
+          # but a per-tutorial author is often a fork contributor who is NOT
+          # assignable on the source repo — passing them to `gh issue create`
+          # would fail the WHOLE create (no issue at all). So we create first
+          # (never blocked by a bad assignee) and best-effort assign after; the
+          # @-mention in the body emails the author regardless of assignability.
+          # Body is built with a single printf (no heredoc — an unindented
+          # heredoc breaks the YAML block scalar; and per-line $(printf) would
+          # have its trailing newlines stripped by command substitution,
+          # collapsing the layout).
           DETAIL_BLOCK=""
           [ -n "$DETAIL_LINE" ] && DETAIL_BLOCK="${DETAIL_LINE}"$'\n'
-          BODY="$(printf '%s\n\n**Automated alert (#1373).** A **%s** content rebuild failed.\n\n- **Channel:** %s\n- **Trigger:** %s\n- **First failing run:** %s\n%s\nThis issue is deduplicated per channel: each additional consecutive failure adds a comment below (so the comment count is the consecutive-failure count). A subsequent successful rebuild auto-closes this issue and resets the streak.\n\nConsecutive failures: **1**\n' \
-            "$MARKER" "$CHANNEL" "$CHANNEL" "$TRIGGER" "$RUN_URL" "$DETAIL_BLOCK")"
+
+          # @-mention every assignee in the body so the author is emailed even
+          # when they can't be assigned (fork contributors on a source repo).
+          MENTION_LINE=""
+          for a in "${_A[@]}"; do
+            a="$(echo "$a" | tr -d '[:space:]')"
+            [ -n "$a" ] && MENTION_LINE="${MENTION_LINE} @${a}"
+          done
+
+          if [ -n "$SLUG" ]; then
+            # Per-tutorial author content error (missing/misnamed source file).
+            MENTION_BLOCK=""
+            [ -n "$MENTION_LINE" ] && MENTION_BLOCK="- **Author:**${MENTION_LINE}"$'\n'
+            BODY="$(printf '%s\n\n**Automated alert (#1373).** A **%s**-channel content rebuild could not fetch the source markdown for tutorial `%s`.\n\n- **Tutorial slug:** %s\n- **Channel:** %s\n- **Trigger:** %s\n- **Run:** %s\n%s%s\n**Most likely cause:** the primary tutorial markdown is missing or misnamed. It MUST be at `tutorials/%s/%s.md` (folder name and file name both equal the slug). If the file is named something else (e.g. `architecture.md`), rename it to `%s.md`.\n\nThe rebuild **skipped this tutorial and continued** — the rest of the channel published normally. Fix the source file and re-trigger the QA rebuild for this slug; a successful rebuild auto-closes this issue.\n' \
+              "$MARKER" "$CHANNEL" "$SLUG" "$SLUG" "$CHANNEL" "$TRIGGER" "$RUN_URL" "$DETAIL_BLOCK" "$MENTION_BLOCK" "$SLUG" "$SLUG" "$SLUG")"
+          else
+            BODY="$(printf '%s\n\n**Automated alert (#1373).** A **%s** content rebuild failed.\n\n- **Channel:** %s\n- **Trigger:** %s\n- **First failing run:** %s\n%s\nThis issue is deduplicated per channel: each additional consecutive failure adds a comment below (so the comment count is the consecutive-failure count). A subsequent successful rebuild auto-closes this issue and resets the streak.\n\nConsecutive failures: **1**\n' \
+              "$MARKER" "$CHANNEL" "$CHANNEL" "$TRIGGER" "$RUN_URL" "$DETAIL_BLOCK")"
+          fi
+
           NEW_URL="$(gh issue create --repo "$REPO" \
-            --title "🚨 ${CHANNEL} content rebuild failing" \
+            --title "$ISSUE_TITLE" \
             --label "$LABEL" \
-            "${ASSIGNEE_FLAGS[@]}" \
             --body "$BODY")" \
-            && echo "Filed new ${CHANNEL} rebuild-failure issue: ${NEW_URL}" \
-            || echo "::warning::Failed to create ${CHANNEL} rebuild-failure issue"
+            && echo "Filed new issue: ${NEW_URL}" \
+            || { echo "::warning::Failed to create issue in ${REPO} (title: ${ISSUE_TITLE})"; exit 0; }
+
+          # Best-effort assign — tolerate an unassignable (fork-contributor)
+          # author; the @-mention already emailed them. Never fail the step.
+          if [ "${#ASSIGNEE_FLAGS[@]}" -gt 0 ]; then
+            gh issue edit "$NEW_URL" --repo "$REPO" "${ASSIGNEE_FLAGS[@]}" >/dev/null 2>&1 \
+              || echo "::notice::Could not assign ${ASSIGNEES} on ${NEW_URL} (likely not a collaborator on ${REPO}); @-mention still notifies them."
+          fi
           exit 0
         fi