Add Copilot Workshops sync workflow + Learning Hub i18n (#2325)

Adds an agentic (gh-aw) workflow that mirrors the multi-harness workshop from github-samples/copilot-workshops into the Learning Hub, plus the Starlight infrastructure it needs: GitHub-admonition rendering, i18n locales with English at the site root, and a language picker that only appears when a page has a non-English translation. Copilot-Session: 9e1d1a4c-a422-4cae-8ea7-b3d5171f58e3 Co-authored-by: GeekTrainer <GeekTrainer@users.noreply.github.com> Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
2026-07-17 11:23:27 +00:00 · 2026-07-16 17:06:29 -07:00
parent 7c2009f436
commit 65ef449bda
6 changed files with 2015 additions and 0 deletions
@@ -0,0 +1,225 @@
+---
+name: "Copilot Workshops Content Sync"
+description: "Weekly check for updates to the Copilot Workshops source repo (github-samples/copilot-workshops). Opens a PR to keep the Learning Hub mirror aligned when substantive upstream course changes are detected."
+on:
+  schedule: weekly
+permissions:
+  contents: read
+tools:
+  github:
+    toolsets: [repos]
+  cache-memory: true
+safe-outputs:
+  create-pull-request:
+    labels: [automated-update, learning-hub, copilot-workshops]
+    title-prefix: "[bot] "
+    base-branch: main
+---
+
+# Copilot Workshops Content Sync
+
+You are a documentation sync agent for the **awesome-copilot** Learning Hub. Your job is to keep the **Copilot Workshops** mirror aligned with its upstream source course, and to perform the **initial import** if the mirror does not exist yet.
+
+## Source of truth
+
+- **Repository:** [`github-samples/copilot-workshops`](https://github.com/github-samples/copilot-workshops)
+- **Branch / ref to read from:** `main` (the repository's default branch)
+
+> [!NOTE]
+> The markdown body of this workflow can be edited directly on GitHub.com without recompilation. If the upstream repository is renamed or the content moves, update the repository, ref, or path values in this section and in the layout descriptions below.
+
+The upstream course is a single workshop, **"Hands-on with GitHub Copilot's agents"**, presented as four independent **harnesses** the learner can choose between. The content lives directly under `docs/` (plain GitHub-flavoured markdown — this is the same content rendered on github.com and, separately, by the upstream repo's own Astro site):
+
+```
+docs/
+├── README.md           # "choose your harness" landing page (frontmatter slug: index)
+├── _images/            # shared screenshots referenced by all harnesses (via ../_images/…)
+├── vscode/             # README.md (overview) + 0-prerequisites … 6-iterating
+├── cli/                # README.md (overview) + 0-prerequisites … 8-review
+├── app/                # README.md (overview) + 0-prerequisites … 8-review
+├── cloud/              # README.md (overview) + 0-prerequisites … 5-iterating
+├── es-es/              # localized content (see "Localizations" below)
+├── ja-jp/
+├── ko-kr/
+├── pt-br/
+└── zh-cn/
+```
+
+Key conventions in the upstream content:
+
+- **Overview pages are `README.md`** (not `index.md`), each with frontmatter `title`, `slug`, `authors`, `lastUpdated`.
+- **Lesson pages** are `<n>-<name>.md` with frontmatter `title`, often `description`, `authors`, `lastUpdated`.
+- **Images** are referenced relative to the harness folder as `../_images/<file>.png`, resolving to `docs/_images/`.
+- **Intra-course links** are reference-style relative paths, e.g. `0-prerequisites/`, `vscode/`, `../cli/3-generating-code/`.
+- **Callouts** use GitHub admonition syntax (`> [!NOTE]`, `> [!TIP]`, `> [!IMPORTANT]`, `> [!WARNING]`, `> [!CAUTION]`).
+
+## Local mirror layout
+
+The canonical English mirror lives under the Learning Hub:
+
+```
+website/src/content/docs/learning-hub/copilot-workshops/
+├── index.md            # mirrored landing page (from upstream docs/README.md)
+├── vscode/
+│   ├── index.md        # from upstream docs/vscode/README.md
+│   ├── 0-prerequisites.md
+│   └── … (one file per lesson)
+├── cli/
+├── app/
+└── cloud/
+```
+
+Mirrored images live under `website/public/images/learning-hub/copilot-workshops/` (mirror the upstream `_images/` filenames; keep them flat unless upstream introduces subfolders).
+
+### Localizations
+
+The upstream repo ships localized content under per-locale folders (`docs/<locale>/…`) using these locale directories: `es-es`, `ja-jp`, `ko-kr`, `pt-br`, `zh-cn`. Localization coverage is partial and grows over time (at time of writing, the localized `app` harness plus a localized landing `README.md` exist for each locale; other harnesses may not be translated yet).
+
+The website uses **Starlight internationalization** with English as the root (unprefixed) locale. Localized pages therefore live under a locale-prefixed content path that mirrors the English tree:
+
+```
+website/src/content/docs/<locale>/learning-hub/copilot-workshops/…
+```
+
+For example, the Spanish version of the app harness overview maps like this:
+
+| Upstream | Local mirror |
+| --- | --- |
+| `docs/es-es/README.md` | `website/src/content/docs/es-es/learning-hub/copilot-workshops/index.md` |
+| `docs/es-es/app/README.md` | `website/src/content/docs/es-es/learning-hub/copilot-workshops/app/index.md` |
+| `docs/es-es/app/2-add-star-rating.md` | `website/src/content/docs/es-es/learning-hub/copilot-workshops/app/2-add-star-rating.md` |
+
+Use the **same locale directory names as upstream** (`es-es`, `ja-jp`, `ko-kr`, `pt-br`, `zh-cn`) so they match the `locales` keys configured in `website/astro.config.mjs`. Starlight automatically falls back to the English page for any localized page that does not exist upstream, so you only need to mirror the localized files that actually exist — do **not** invent translations or copy English text into locale folders.
+
+Localized pages share the English images: keep their image references pointing at the same site-absolute `/images/learning-hub/copilot-workshops/…` paths (do not duplicate images per locale).
+
+## Navigation wiring
+
+Navigation is wired in three places:
+
+- `website/astro.config.mjs` — the sidebar group **"Copilot Workshops"**, with a nested sub-group per harness. Starlight applies one sidebar across all locales and auto-prefixes links for the active locale, so you only configure the English (root) slugs here.
+- `website/src/content/docs/learning-hub/index.md` — a short entry linking to the workshop.
+- `website/src/content/docs/learning-hub/copilot-workshops/index.md` — the mirrored landing page whose harness/lesson tables link to the local pages.
+
+## Step 1 — Determine what's new upstream
+
+1. Read `cache-memory` and look for a file named `copilot-workshops-sync-state.json`. It may contain:
+   - `last_synced_sha` — the most recent commit SHA you processed on your previous run
+   - `last_synced_at` — a filesystem-safe timestamp in the format `YYYY-MM-DD-HH-MM-SS`
+
+2. Use GitHub tools to fetch recent commits from `github-samples/copilot-workshops` on the `main` branch:
+   - If `last_synced_sha` exists, list commits **since that SHA** (stop once you reach it).
+   - If no cached state exists, treat this as a **first run**: you will perform a full initial import (see Step 4), so gather the full current state of the upstream `docs/` tree rather than a commit delta.
+
+3. Identify which files changed (or, on a first run, which files exist). Focus on:
+   - Markdown files under `docs/` — the landing `README.md`, harness overview `README.md` files, per-lesson `<n>-*.md` files, and their localized equivalents under `docs/<locale>/`
+   - Supporting assets in `docs/_images/`
+   - Any change to harness structure, lesson order, or lesson titles
+
+4. If a local mirror **already exists** and **no commits** were found since the last sync, do **not** immediately no-op on the strength of the cached SHA alone. The cached `last_synced_sha` is only advanced optimistically when a PR is opened (see Step 5), so a previously opened sync PR that was later **closed or rejected** can leave the cache pointing at a commit whose content never actually reached `main`. Before short-circuiting, **verify the checked-out mirror is genuinely consistent with the current upstream content** (spot-check that every upstream harness, lesson, localized page, and image is present in the mirror and not obviously stale). Only if the mirror both is up to date on SHA **and** matches upstream should you call the `noop` safe output with a message like: "No new commits found in `github-samples/copilot-workshops@main` since last sync (`<last_synced_sha>`), and the local mirror matches upstream. No action needed." If the SHA suggests nothing changed but the mirror is actually missing or stale, proceed to Step 2+ and open a PR anyway so a rejected/closed earlier PR cannot permanently hide the update.
+
+## Step 2 — Read the upstream content
+
+For each relevant upstream file, use GitHub tools to fetch the **current file contents** from `github-samples/copilot-workshops` at `main`. Pay close attention to:
+
+- New harnesses, lessons, sections, commands, flags, or concepts introduced
+- Renamed, reordered, or restructured lessons or harnesses
+- Deprecated lessons or workflows that have been removed
+- Updated screenshots, image references, or code examples
+- New or updated localized files under `docs/<locale>/`
+- Links to new official documentation or resources
+
+Determine harness order and lesson order from the numeric filename prefixes (`0-`, `1-`, …) and the overview `README.md` lesson tables.
+
+## Step 3 — Compare against the local Learning Hub content
+
+Read the local files under `website/src/content/docs/learning-hub/copilot-workshops/` (English) and `website/src/content/docs/<locale>/learning-hub/copilot-workshops/` (localized), plus the local assets under `website/public/images/learning-hub/copilot-workshops/`.
+
+Map the upstream changes to the relevant local file(s). Ask yourself:
+
+- Is the mirror missing any upstream harness, lesson, section, assignment, example, visual, or localized page?
+- Is any existing mirrored content now outdated or incorrect based on upstream changes?
+- Do internal links, harness/lesson cross-links, or asset paths need updating so the mirrored pages still work on the website?
+- Do the Astro frontmatter fields (especially `lastUpdated`) need updating because a mirrored page changed?
+
+If the mirror already exists and is fully consistent with upstream — or the upstream changes are non-substantive (e.g. only CI config, typo fixes, or internal tooling changes) — stop here and call the `noop` safe output with a brief explanation. Still update the cache with the latest commit SHA.
+
+## Step 4 — Update (or create) the Learning Hub files
+
+Edit the local docs, assets, and navigation so the website remains a **source-faithful mirror** of the upstream course. On a **first run**, create the full mirror from scratch: all four harness folders, every lesson, the landing page, all referenced images, every localized page that exists upstream, and the navigation wiring.
+
+### File mapping rules
+
+- Upstream `docs/README.md` → `learning-hub/copilot-workshops/index.md`
+- Upstream `docs/<harness>/README.md` → `learning-hub/copilot-workshops/<harness>/index.md`
+- Upstream `docs/<harness>/<n>-*.md` → `learning-hub/copilot-workshops/<harness>/<n>-*.md`
+- Upstream `docs/<locale>/README.md` → `<locale>/learning-hub/copilot-workshops/index.md`
+- Upstream `docs/<locale>/<harness>/README.md` → `<locale>/learning-hub/copilot-workshops/<harness>/index.md`
+- Upstream `docs/<locale>/<harness>/<n>-*.md` → `<locale>/learning-hub/copilot-workshops/<harness>/<n>-*.md`
+- Upstream `docs/_images/<file>` → `website/public/images/learning-hub/copilot-workshops/<file>`
+
+### Mirror-first authoring rules
+
+1. Preserve upstream wording, headings, section order, lessons, assignments, and overall harness flow as closely as practical. Do **not** summarize, reinterpret, or "website-optimize" the course into a different learning experience.
+
+2. Only adapt what the website requires:
+   - **Frontmatter.** Keep the upstream `title` (and `description` if present). **Remove the upstream `slug` field** (routing on this site is path-based, and a stray `slug` would break the mirror's routes). Ensure these two fields the Learning Hub uses are present on every mirrored page:
+     - `authors:` — replace the upstream author list with a single-item list `- GitHub Copilot Learning Hub Team`
+     - `lastUpdated:` — today's date in `YYYY-MM-DD` format (bump only on pages whose mirrored content changed; otherwise preserve the existing value)
+   - **GitHub admonitions.** The website renders GitHub admonition syntax (`> [!NOTE]`, `> [!TIP]`, `> [!IMPORTANT]`, `> [!WARNING]`, `> [!CAUTION]`) via a remark plugin, so **preserve admonitions exactly as written upstream** — do not convert them to Starlight `:::` asides and do not strip the `[!...]` markers. Keep the marker on its own `>`-prefixed line with the body on subsequent `>`-prefixed lines.
+   - **Image paths.** Rewrite upstream relative image references to site-absolute paths under `/images/learning-hub/copilot-workshops/`. Upstream uses a relative `_images/` reference whose depth depends on the file's location: English harness pages use `../_images/<file>.png`, while localized pages (which sit one directory deeper under `docs/<locale>/<harness>/`) use `../../_images/<file>.png`. **Collapse any leading run of `../` segments** before `_images/` — i.e. rewrite `(../)+_images/<file>` to `/images/learning-hub/copilot-workshops/<file>` regardless of how many `../` precede it (verify no stray `..//images/...` remains). Copy the referenced image files into `website/public/images/learning-hub/copilot-workshops/`. Localized pages reuse the same English image files and paths.
+   - **Internal course links.** Rewrite upstream intra-course links so they resolve on the website. Reference-style relative links like `0-prerequisites/`, `vscode/`, or `../cli/3-generating-code/` must point at the local mirror routes under `/learning-hub/copilot-workshops/<harness>/<lesson>/` (with a trailing slash, matching the site's `trailingSlash: always` setting). An overview link that upstream targets a harness folder (e.g. `vscode/`) maps to `/learning-hub/copilot-workshops/vscode/`. Preserve reference-style link definitions when upstream uses them. **For localized pages, the target path must include the page's locale prefix**, e.g. on a `es-es` page link to `/es-es/learning-hub/copilot-workshops/<harness>/<lesson>/`. Astro/Starlight does **not** rewrite absolute links written in Markdown body content for the active locale (the locale helpers only apply to `.astro` components), so an unprefixed `/learning-hub/…` link inside a translated page would send readers to the English page. Only cross-locale-safe option other than prefixing is to keep the link relative (e.g. `../3-generating-code/`), which resolves within the current locale automatically — prefer explicit locale-prefixed absolute links for clarity.
+   - **Repo-root relative links.** Convert links that are only valid inside the upstream repo (for example `../../.github/...`, `./.github/...`, or `src/...` source-file references) into absolute links to the upstream repo: use `https://github.com/github-samples/copilot-workshops/tree/main/...` for directories and `https://github.com/github-samples/copilot-workshops/blob/main/...` for files.
+
+3. If upstream adds, removes, or renames harnesses or lessons:
+   - Create, delete, or rename the corresponding markdown files under `website/src/content/docs/learning-hub/copilot-workshops/<harness>/` (and the localized equivalents under `website/src/content/docs/<locale>/learning-hub/copilot-workshops/<harness>/`).
+   - Update the **"Copilot Workshops"** sidebar group in `website/astro.config.mjs` so its nested per-harness sub-groups list the Overview link plus each lesson in upstream order, using the upstream lesson titles as labels.
+   - Update `website/src/content/docs/learning-hub/copilot-workshops/index.md` and any harness `index.md` lesson tables to match.
+   - Update the `website/src/content/docs/learning-hub/index.md` entry only if the workshop's landing description or link must change.
+
+### Navigation wiring details
+
+- In `website/astro.config.mjs`, add or maintain a top-level sidebar group labelled `"Copilot Workshops"`. Give it an `items` array containing one nested group per harness (labels: `VS Code`, `Copilot CLI`, `Copilot App`, `Copilot Cloud Agent`). Each nested group should start with an `Overview` entry that links to `/learning-hub/copilot-workshops/<harness>/` and then list each lesson slug (e.g. `learning-hub/copilot-workshops/app/0-prerequisites`). Follow the exact style already used by the existing `"Copilot CLI for Beginners"` group.
+- Place the new group in a sensible position relative to the existing Learning Hub groups (after `"Copilot CLI for Beginners"` is a natural fit).
+- Do **not** add locale-prefixed slugs to the sidebar; Starlight derives localized navigation from the single root sidebar automatically.
+- Every root slug you add to the sidebar **must** correspond to a real mirrored English markdown file, or the website build will fail.
+
+## Step 5 — Update the sync state cache
+
+Write an updated `copilot-workshops-sync-state.json` to `cache-memory` with:
+
+```json
+{
+  "last_synced_sha": "<latest commit SHA from github-samples/copilot-workshops@main>",
+  "last_synced_at": "<YYYY-MM-DD-HH-MM-SS>",
+  "files_reviewed": ["<list of upstream files you compared>"],
+  "files_updated": ["<list of local Learning Hub files you edited>"]
+}
+```
+
+> [!NOTE]
+> The cached `last_synced_sha` is an **optimization hint, not a source of truth**. Because a PR opened by this workflow may later be closed or rejected before it merges to `main`, never treat a matching SHA as proof that the mirror is current — Step 1 must independently confirm the checked-out mirror actually matches upstream before taking the no-op path. Advancing the SHA here is acceptable only because that consistency check will re-detect and re-open any update that a rejected PR left unmerged.
+
+## Step 6 — Open a pull request
+
+Create a pull request with your changes using the `create-pull-request` safe output. Use `main` as the base branch for all work related to this workflow. The PR body must include:
+
+1. **What changed upstream** — a concise summary of the commits and file changes found in `github-samples/copilot-workshops` (or, on a first run, a note that this is the initial import of the workshop)
+2. **What was updated locally** — list each mirrored Learning Hub file or asset you created or edited and what changed, including any navigation wiring and any localized pages
+3. **Source links** — links to the relevant upstream files or commits on `main`
+4. A note that the markdown body of this workflow can be edited directly on GitHub.com without recompilation
+
+If there is nothing to change after your analysis, do **not** open a PR. Instead, call the `noop` safe output.
+
+## Guidelines
+
+- The canonical course content lives in `website/src/content/docs/learning-hub/copilot-workshops/` (English) and `website/src/content/docs/<locale>/learning-hub/copilot-workshops/` (localized); do not recreate legacy duplicates elsewhere.
+- Prefer changes within the course docs and `website/public/images/learning-hub/copilot-workshops/`.
+- Only edit `website/astro.config.mjs` or `website/src/content/docs/learning-hub/index.md` when upstream course structure or navigation truly requires it.
+- Preserve existing frontmatter fields; remove only the upstream `slug`, and add/update `authors` and `lastUpdated` (and `description` if genuinely warranted).
+- Preserve GitHub admonition syntax exactly; the site renders it natively.
+- Only mirror localized files that actually exist upstream; rely on Starlight's fallback for the rest, and never fabricate translations.
+- Keep the course source-faithful; avoid summaries or interpretive rewrites.
+- Do not auto-merge; the PR is for human review.
+- If you are uncertain whether an upstream change warrants a Learning Hub update, err on the side of creating the PR — a human reviewer can always decline.
+- Always call either `create-pull-request` or `noop` at the end of your run so the workflow clearly signals its outcome.