Skip to content

Commit 170d357

Browse files
author
Kristopher Turner
committed
docs: add repo-management setup and automation docs
Documents branch protection, labels, secrets, and every GitHub Actions workflow for this repository. Updates the repository-management standard and repo-standard.md to reflect the new flat structure (setup.md, automation.md, scripts/) replacing the old plans/checklists/roadmaps layout.
1 parent de1372f commit 170d357

6 files changed

Lines changed: 524 additions & 22 deletions

File tree

‎.github/repo-standard.md‎

Lines changed: 5 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -102,16 +102,13 @@ The ownership model should be broadly consistent across the portfolio, but it do
102102

103103
Every repo must have a root-level `repo-management/` folder with a `README.md`.
104104

105-
Use `repo-management/` for:
105+
Use `repo-management/` to document **how the repo works**:
106106

107-
- plans
108-
- checklists
109-
- roadmaps
110-
- reports
111-
- repo-management scripts
112-
- working notes
107+
- `setup.md` — branch protection, labels, secrets, CODEOWNERS, replication guide
108+
- `automation.md` — every GitHub Action: what it does, why, triggers, secrets
109+
- `scripts/` — repo-management helper scripts
113110

114-
Do not use `repo-management/` as the canonical location for cross-repo standards.
111+
Do not use `repo-management/` for work tracking (use GitHub Projects), standards (use `standards/`), or user-facing docs.
115112

116113
---
117114

‎repo-management/README.md‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
# Repo Management
2+
3+
This folder documents how this repository is configured and how its automation works.
4+
5+
## Contents
6+
7+
| File | Purpose |
8+
|------|---------|
9+
| [`setup.md`](setup.md) | Branch protection, labels, secrets, CODEOWNERS, and replication guide |
10+
| [`automation.md`](automation.md) | Every GitHub Actions workflow — what it does, when it runs, secrets required |
11+
| `scripts/` | Repo-management helper scripts |
12+
13+
## Canonical References
14+
15+
- Label definitions: `.github/labels.yml` (this repo — source of truth for all repos)
16+
- Repository standard: `.github/repo-standard.md`
17+
- Standards source: `standards/`
18+
- Repository management model: `standards/repository-management.mdx`

‎repo-management/automation.md‎

Lines changed: 106 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,106 @@
1+
# Automation
2+
3+
Documents every GitHub Actions workflow in this repository.
4+
5+
---
6+
7+
## Workflow Summary
8+
9+
| File | Name | Trigger | Purpose |
10+
|------|------|---------|---------|
11+
| `add-to-project.yml` | Add to Project | Issues/PRs opened or labeled | Adds items to the org project board and sets custom fields |
12+
| `deploy.yml` | Deploy Azure Local Docs to GitHub Pages | Push to `main` | Builds Docusaurus site and deploys to GitHub Pages |
13+
| `release-please.yml` | Release Please | Push to `main` | Automates CHANGELOG and release tags from conventional commits |
14+
| `sync-labels.yml` | Sync Labels | Push to `main` touching `.github/labels.yml` | Applies label definitions to this repo |
15+
| `validate-repo-structure.yml` | Validate Repo Structure | PR to `main` | Checks required files and directories are present |
16+
17+
---
18+
19+
## add-to-project.yml
20+
21+
**Trigger:** `issues` (opened, labeled) and `pull_request` (opened, labeled)
22+
**Permissions required:** `ADD_TO_PROJECT_PAT` — classic PAT with `project` scope
23+
24+
**What it does:**
25+
26+
1. **Add to Project** — uses `actions/add-to-project` to add the issue or PR to org project board (`AzureLocal/projects/3`). Outputs the created item ID.
27+
2. **Set Fields** (issues only, on success of step 1) — calls `gh project item-edit` to set three custom fields on the project board item:
28+
- **ID** — sets a text field to `DOCS-{number}`
29+
- **Solution** — maps a `solution/*` label to a single-select option (e.g. `solution/docs-site` → option ID `409662e1`)
30+
- **Priority** — maps a `priority/*` label to a single-select option (`critical` → `74334e8d`, etc.)
31+
- **Category** — maps a `type/*` label to a single-select option (`type/feature` → `7a4fa8ea`, etc.)
32+
33+
**Notes:**
34+
- Field IDs and option IDs are project-board-specific constants — do not change unless the project board is re-created.
35+
- PRs are added to the board but fields are not set (the `set-fields` job has `if: github.event_name == 'issues'`).
36+
37+
---
38+
39+
## deploy.yml
40+
41+
**Trigger:** Push to `main` (any path except `Readme.md`); manual via `workflow_dispatch`
42+
**Permissions:** `contents: write`, `pages: write`, `id-token: write`
43+
44+
**What it does:**
45+
46+
1. Checks out code
47+
2. Sets up Node.js 22
48+
3. Runs `npm install`
49+
4. Checks formatting with Prettier (`src/**/*.{js,jsx,json,css,md}`)
50+
5. Runs Vale prose linting on `docs/` — `continue-on-error: true` so failures are annotations not blockers
51+
6. Builds the Docusaurus site (`npm run build` → `build/` directory)
52+
7. Deploys to GitHub Pages using `peaceiris/actions-gh-pages`, publishing `build/` to the `gh-pages` branch
53+
54+
**Notes:**
55+
- The `gh-pages` branch is fully managed by this workflow. Never commit to it directly.
56+
- Vale linting is informational — it will annotate PRs but not block the deploy.
57+
- Prettier failures **do** block the deploy. Run `npx prettier --write` locally before pushing.
58+
59+
---
60+
61+
## release-please.yml
62+
63+
**Trigger:** Push to `main`
64+
**Permissions:** `contents: write`, `pull-requests: write`
65+
66+
**What it does:**
67+
68+
Uses `googleapis/release-please-action@v4` to maintain an automated release PR. When conventional commits (`feat:`, `fix:`, `chore:`, etc.) land on `main`, Release Please:
69+
1. Creates or updates a release PR updating `CHANGELOG.md` and bumping the version
70+
2. When that PR is merged, creates a GitHub release and tag
71+
72+
Configuration is in `release-please-config.json` at the repo root.
73+
74+
---
75+
76+
## sync-labels.yml
77+
78+
**Trigger:** Push to `main` touching `.github/labels.yml`; manual via `workflow_dispatch`
79+
**Permissions:** `contents: read`, `issues: write`
80+
81+
**What it does:**
82+
83+
Uses `EndBug/label-sync@v2` to apply the label definitions in `.github/labels.yml` to this repository. `delete-other-labels: false` means existing labels not in the file are left alone.
84+
85+
**This repo is the label source of truth.** When `labels.yml` changes, this workflow applies labels to the current repo only. To push labels to other repos in the org, run the workflow with a PAT that has repo access to other repos, or trigger equivalent workflows in each downstream repo.
86+
87+
---
88+
89+
## validate-repo-structure.yml
90+
91+
**Trigger:** PR to `main`
92+
93+
**What it does:**
94+
95+
Checks that required files and directories are present on the PR branch. Fails the PR if any are missing.
96+
97+
| Check | Required Items |
98+
|-------|---------------|
99+
| Root files | `README.md`, `CONTRIBUTING.md`, `LICENSE`, `CHANGELOG.md`, `.gitignore` |
100+
| Directories | `docs/`, `.github/` |
101+
| PR template | `.github/PULL_REQUEST_TEMPLATE.md` |
102+
| Config structure (if `config/` exists) | `config/variables.example.yml`, `config/schema/variables.schema.json` |
103+
104+
**Notes:**
105+
- This repo does not have a `config/` directory, so the config check is always skipped here.
106+
- Failures show as GitHub Annotations in the PR checks panel.

0 commit comments

Comments
 (0)