|
| 1 | +# Agentic Workflows (`gh-aw`) |
| 2 | + |
| 3 | +This directory contains GitHub **agentic workflows** that automatically |
| 4 | +translate English documentation into Japanese when changes are pushed to |
| 5 | +`vnext`. |
| 6 | + |
| 7 | +## Workflow files |
| 8 | + |
| 9 | +| Source (`.md`) | Compiled (`.lock.yml`) | Watches | |
| 10 | +|---|---|---| |
| 11 | +| `workflows/sync-jp-docs-angular.md` | `workflows/sync-jp-docs-angular.lock.yml` | `docs/angular/src/content/en/**` on `vnext` | |
| 12 | +| `workflows/sync-jp-docs-xplat.md` | `workflows/sync-jp-docs-xplat.lock.yml` | `docs/xplat/src/content/en/**` on `vnext` | |
| 13 | + |
| 14 | +The `.md` files are the human-editable source. The `.lock.yml` files are |
| 15 | +auto-generated and are what GitHub Actions actually executes. **Do not edit |
| 16 | +`.lock.yml` files directly.** After changing a workflow `.md`, run `gh aw compile` |
| 17 | +and commit the regenerated `.lock.yml` file(s) (and `actions-lock.json` if it changed). |
| 18 | + |
| 19 | +## How to update a workflow |
| 20 | + |
| 21 | +### Prerequisites |
| 22 | + |
| 23 | +1. [GitHub CLI](https://cli.github.com/) installed |
| 24 | +2. The `gh-aw` extension installed: |
| 25 | + ```bash |
| 26 | + gh extension install github/gh-aw |
| 27 | + ``` |
| 28 | +3. Authenticated with `gh auth login` |
| 29 | + |
| 30 | +### Steps |
| 31 | + |
| 32 | +1. Edit the `.md` file under `.github/workflows/`. |
| 33 | +2. Run from the repo root: |
| 34 | + ```bash |
| 35 | + gh aw compile |
| 36 | + ``` |
| 37 | + This regenerates the corresponding `.lock.yml` file(s) and updates |
| 38 | + `.github/aw/actions-lock.json` if action SHAs changed. |
| 39 | +3. Commit **both** the `.md` and the `.lock.yml` together (plus |
| 40 | + `actions-lock.json` if it changed). |
| 41 | +4. Push to `vnext`. |
| 42 | + |
| 43 | +For more information: https://github.github.com/gh-aw/introduction/overview/ |
| 44 | + |
| 45 | +## Required GitHub secrets |
| 46 | + |
| 47 | +The following secrets must be configured at the repository level |
| 48 | +(Settings → Secrets and variables → Actions) for the agent workflows to |
| 49 | +run: |
| 50 | + |
| 51 | +| Secret | Required | Purpose | |
| 52 | +|---|---|---| |
| 53 | +| `GITHUB_TOKEN` | Auto (built-in) | Standard token — nothing to provision | |
| 54 | +| `COPILOT_GITHUB_TOKEN` | **Yes** | Authenticates the Copilot CLI engine that drives the translation agent. Without it, the workflow fails immediately. | |
| 55 | +| `GH_AW_GITHUB_TOKEN` | Recommended | Elevated token the agent uses to create the translation PR. Falls back to `GITHUB_TOKEN` if unset. | |
| 56 | +| `GH_AW_GITHUB_MCP_SERVER_TOKEN` | Optional | Token for the embedded GitHub MCP read-only tools. Falls back to `GITHUB_TOKEN`. | |
| 57 | +| `GH_AW_CI_TRIGGER_TOKEN` | Optional | Triggers CI on the auto-created PR. Only needed if you want checks to run on bot PRs. | |
| 58 | + |
| 59 | +These are the same secrets used in the old `igniteui-docfx` and |
| 60 | +`igniteui-xplat-docs` repositories. |
| 61 | + |
0 commit comments