Skip to content

Commit 5111b3c

Browse files
olivierlacanolivierlacan
authored
Clarify the Actions list: one CI workflow, explicit deploy naming (#728)
1 parent ca677fc commit 5111b3c

6 files changed

Lines changed: 126 additions & 91 deletions

File tree

‎.github/workflows/README.md‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
# What's in the Actions list
2+
3+
The Workflows sidebar mixes workflows defined in this directory with entries
4+
GitHub adds on its own, which makes it hard to tell what deploys the site and
5+
what merely validates it. The short version: **only "Deploy site (manual)"
6+
changes keepachangelog.com, and only when run by hand.** Everything else is
7+
validation, release bookkeeping, or GitHub-managed automation.
8+
9+
## Defined in this repo
10+
11+
| Workflow | File | Trigger | What it does |
12+
|----------|------|---------|--------------|
13+
| **CI checks** | [`ci.yml`](ci.yml) | push + PR to `main` | Validation only. Runs the Rake suite (unit tests + full Middleman build) and the axe-core accessibility audit. Never deploys. |
14+
| **Deploy site (manual)** | [`deploy.yml`](deploy.yml) | manual (`workflow_dispatch`) | The only way the live site changes. Builds the production site and pushes it to the `gh-pages` branch that GitHub Pages serves. |
15+
| **Release from changelog** | [`release.yml`](release.yml) | push to `main` touching `CHANGELOG.md`, or manual | Creates tags and GitHub Releases from CHANGELOG.md entries, gated behind the `release` environment's approval. Touches Releases only, never the site. |
16+
17+
## Added by GitHub (no file in this repo)
18+
19+
These appear in the same list but are configured in the repository's
20+
**Settings**, not here:
21+
22+
| Entry | Where it comes from | What it does |
23+
|-------|---------------------|--------------|
24+
| **pages-build-deployment** | GitHub Pages | Runs automatically whenever `gh-pages` is pushed (i.e. right after "Deploy site (manual)") and publishes that branch. It's the second half of every deploy — not a separate deploy path. |
25+
| **CodeQL** | Settings → Code security | GitHub's default-setup code scanning. |
26+
| **Dependabot Updates** | Settings → Code security + [`dependabot.yml`](../dependabot.yml) | Opens dependency update PRs. |
27+
| **Dependency Graph** | Settings → Code security | Indexes the dependency manifest. |
28+
29+
## Retired names
30+
31+
"Ruby" (`ruby.yml`) and "Accessibility" (`accessibility.yml`) were merged into
32+
**CI checks** — same jobs, same check names (`test (3.3)` and `axe`), one
33+
workflow. The old names linger in the sidebar as long as their past runs are
34+
retained.

‎.github/workflows/accessibility.yml‎

Lines changed: 0 additions & 45 deletions
This file was deleted.

‎.github/workflows/ci.yml‎

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
name: CI checks
2+
3+
# Validation only — nothing in this workflow deploys. Every push and pull
4+
# request against main builds the site fresh and checks it two ways:
5+
#
6+
# test — the Rake suite: unit tests (version routing, changelog pinning,
7+
# release tooling) plus a full Middleman build.
8+
# axe — the axe-core accessibility audit (WCAG 2.1 A/AA + best-practice)
9+
# of the 2.0 page across light/dark, desktop/mobile, and the
10+
# pinned-header and open-picker states. Fails on any violation.
11+
#
12+
# The live site only changes when the "Deploy site (manual)" workflow is run
13+
# from the Actions tab. See .github/workflows/README.md for the full map of
14+
# everything that appears in the Actions list.
15+
#
16+
# This file replaced ruby.yml ("Ruby") and accessibility.yml ("Accessibility");
17+
# the job ids (and so the check names "test (3.3)" and "axe") are unchanged.
18+
19+
on:
20+
push:
21+
branches: [ "main" ]
22+
pull_request:
23+
branches: [ "main" ]
24+
25+
permissions:
26+
contents: read
27+
28+
jobs:
29+
test:
30+
runs-on: ubuntu-latest
31+
strategy:
32+
matrix:
33+
ruby-version: ['3.3']
34+
35+
steps:
36+
- uses: actions/checkout@v4
37+
38+
- name: Set up Ruby
39+
uses: ruby/setup-ruby@v1
40+
with:
41+
ruby-version: ${{ matrix.ruby-version }}
42+
bundler-cache: true # runs 'bundle install' and caches installed gems automatically
43+
44+
- name: Run tests
45+
run: bin/rake test
46+
47+
axe:
48+
runs-on: ubuntu-latest
49+
steps:
50+
- uses: actions/checkout@v4
51+
52+
- name: Set up Ruby
53+
uses: ruby/setup-ruby@v1
54+
with:
55+
ruby-version: '3.3'
56+
bundler-cache: true
57+
58+
- name: Set up Node
59+
uses: actions/setup-node@v4
60+
with:
61+
node-version: '20'
62+
cache: 'npm'
63+
64+
- name: Install npm dependencies
65+
run: npm ci
66+
67+
- name: Install Playwright Chromium
68+
run: npx playwright install --with-deps chromium
69+
70+
- name: Build site
71+
run: bundle exec middleman build
72+
73+
- name: Run axe accessibility audit
74+
# The Playwright config serves ./build and the spec audits /en/2.0.0/.
75+
run: npx playwright test test/visual/a11y.spec.js --project=chromium

‎.github/workflows/deploy.yml‎

Lines changed: 12 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,21 @@
1-
name: Deploy
1+
name: Deploy site (manual)
22

3-
# Manual deploy. Builds the production site and publishes it to the gh-pages
4-
# branch that GitHub Pages serves at keepachangelog.com — the same thing
5-
# `rake deploy` does locally, but reproducibly from CI. Trigger it from the
6-
# Actions tab ("Run workflow"); you can pick which branch to build from.
3+
# The ONLY workflow that changes the live site. Builds the production site and
4+
# publishes it to the gh-pages branch that GitHub Pages serves at
5+
# keepachangelog.com — the same thing `rake deploy` does locally, but
6+
# reproducibly from CI. Trigger it from the Actions tab ("Run workflow"); you
7+
# can pick which branch to build from.
8+
#
9+
# After this pushes gh-pages, GitHub's own "pages-build-deployment" workflow
10+
# runs automatically to serve the branch — that entry in the Actions list is
11+
# GitHub-managed, not defined in this repo. See .github/workflows/README.md.
712
#
813
# Note: the build uses the default config, so $last_version (currently 1.1.0)
914
# decides the published "latest" version. 2.0 stays behind ?preview=v2 until you
1015
# flip that flag in config.rb.
1116

17+
run-name: Deploy ${{ github.ref_name }} to keepachangelog.com
18+
1219
on:
1320
workflow_dispatch:
1421

‎.github/workflows/release.yml‎

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,10 @@
11
name: Release from changelog
22

3-
# Keeps GitHub Releases in sync with CHANGELOG.md. The changelog is the source of
4-
# truth; every release is derived from it. All the logic lives in (and is tested
5-
# by) tools/changelog_release.rb — this workflow just runs it, in two stages:
3+
# Keeps GitHub Releases in sync with CHANGELOG.md. It creates tags and GitHub
4+
# Releases — it never touches the live site (that's "Deploy site (manual)").
5+
# The changelog is the source of truth; every release is derived from it. All
6+
# the logic lives in (and is tested by) tools/changelog_release.rb — this
7+
# workflow just runs it, in two stages:
68
#
79
# 1. plan — a dry run that writes the proposed releases (and a diff of any
810
# that would change) to the run summary, and reports whether there's

‎.github/workflows/ruby.yml‎

Lines changed: 0 additions & 38 deletions
This file was deleted.

0 commit comments

Comments
 (0)