Skip to main content
webpack-doc-kit uses three workflows located in .github/workflows/.

CI

Runs on every pull request and push to main. Lints code and verifies doc generation is up to date.

Deploy

Triggers on push to main or manually. Builds the full HTML site and deploys it to GitHub Pages.

Sync Webpack

Runs daily at 04:00 UTC. Checks for new webpack commits, regenerates docs, and pushes updates automatically.

​
CI (ci.yml)

Triggers: pull_request (any branch) and push to main. Permissions: contents: read The CI workflow runs two parallel jobs.

​
Job: lint

Runs on every push to main and every pull request.
1

Checkout code

Checks out the repository at the triggering commit.
2

Setup Node.js

Installs the latest LTS release of Node.js with npm caching enabled.
3

Install dependencies

Runs npm ci for a clean, reproducible install.
4

Lint & Format

Runs both checks in sequence:
npm run lint && npm run format:check
The job fails if ESLint reports errors or any file is not formatted correctly.

​
Job: docs-check

Runs on pull requests only (if: github.event_name == 'pull_request'). Verifies that the pages/ directory matches what generate-docs would produce for the pinned webpack commit.
1

Checkout code

Checks out the repository.
2

Read HEAD_COMMIT

Reads the pinned webpack commit SHA from the HEAD_COMMIT file and exposes it as a step output.
echo "ref=$(cat HEAD_COMMIT)" >> "$GITHUB_OUTPUT"
3

Checkout webpack

Clones webpack/webpack at the exact pinned commit into the webpack/ subdirectory.
4

Setup Node.js

Installs the latest LTS release of Node.js with npm caching enabled.
5

Install dependencies

Runs npm ci.
6

Regenerate docs

Runs npm run generate-docs against the pinned webpack source.
7

Check docs freshness

Compares the working tree against the committed pages/ directory:
if ! git diff --quiet pages/; then
  echo "::error::The pages/ directory is out of date. Run 'npm run generate-docs' and commit the changes."
  git diff --stat pages/
  exit 1
fi
The job fails if any file in pages/ differs from what was regenerated, signalling that committed docs are stale.

​
Deploy (deploy.yml)

Triggers: push to main, or manual dispatch via workflow_dispatch. Permissions: contents: read (build job); pages: write + id-token: write (deploy job).
workflow_dispatch is available, so you can trigger a deployment manually from the Actions tab without pushing a commit.
The workflow has two dependent jobs: build then deploy.

​
Job: build

1

Checkout code

Checks out the repository.
2

Read HEAD_COMMIT

Reads the pinned webpack commit SHA from HEAD_COMMIT:
echo "ref=$(cat HEAD_COMMIT)" >> "$GITHUB_OUTPUT"
3

Checkout webpack

Clones webpack/webpack at the pinned commit into the webpack/ subdirectory.
4

Setup Node.js

Installs the latest LTS release of Node.js with npm caching enabled.
5

Install dependencies

Runs npm ci.
6

Build

Creates the out/ directory and runs the full build pipeline:
mkdir out && npm run build
This runs generate-docs (Markdown) then build-html (static HTML).
7

Upload artifact

Uploads the out/ directory as a GitHub Pages artifact using actions/upload-pages-artifact.

​
Job: deploy

Depends on the build job succeeding. Deploys to the github-pages environment.
1

Deploy to GitHub Pages

Uses actions/deploy-pages to publish the artifact uploaded by the build job. The live URL is available as steps.deployment.outputs.page_url.

​
Sync Webpack (sync.yml)

Triggers: Scheduled daily at 04:00 UTC, or manual dispatch via workflow_dispatch. 
schedule:
  - cron: "0 4 * * *"
workflow_dispatch is available, so you can trigger a sync manually from the Actions tab at any time.
This workflow requires contents: write permission because it commits and pushes updated docs directly to the repository. Ensure the repository’s Actions settings allow this for the workflow to succeed.
Permissions: contents: write
1

Checkout code

Checks out the repository.
2

Get latest webpack commit

Fetches the current HEAD of webpack/webpack main and reads the locally pinned commit from HEAD_COMMIT:
LATEST=$(git ls-remote https://github.com/webpack/webpack.git refs/heads/main | cut -f1)
CURRENT=$(cat HEAD_COMMIT)
Both values are written to step outputs for use in subsequent steps.
3

Check for changes

Compares the latest upstream commit against the pinned commit. If they are identical, the remaining steps are skipped and the job exits cleanly.
4

Checkout webpack

(Skipped if no new commit.) Clones webpack/webpack at the new commit into the webpack/ subdirectory.
5

Setup Node.js

(Skipped if no new commit.) Installs the latest LTS release of Node.js with npm caching enabled.
6

Install dependencies

(Skipped if no new commit.) Runs npm ci.
7

Update HEAD_COMMIT

(Skipped if no new commit.) Overwrites HEAD_COMMIT with the new commit SHA:
echo "${{ steps.latest.outputs.latest }}" > HEAD_COMMIT
8

Regenerate docs

(Skipped if no new commit.) Runs npm run generate-docs against the new webpack source to refresh pages/.
9

Commit and push

(Skipped if no new commit.) Stages HEAD_COMMIT and pages/, then commits and pushes as the github-actions[bot] user:
git config user.name "github-actions[bot]"
git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
git add HEAD_COMMIT pages/
git commit -m "chore: sync webpack docs to $(echo ${{ steps.latest.outputs.latest }} | cut -c1-7)"
git push
The commit message includes the first seven characters of the new webpack commit SHA.

Build docs developers (and LLMs) love

Get started for freeTalk to us