feat(workflows): add reusable Docusaurus workflow (DX-2760) by sebawo · Pull Request #1398 · smartcontractkit/.github

sebawo · 2026-01-30T16:52:29Z

Add a single reusable workflow for Docusaurus documentation: build, test (optional), and deploy to GitHub Pages. Remove the former composite actions in favor of the workflow only.

Changes

Added

reusable-docusaurus.yml – One reusable workflow with one job (docusaurus): checkout, setup Node.js (pinned ref), build docs, (optional) run tests, upload pages artifact, deploy to GitHub Pages. Build runs once; no duplicate jobs.

Callers use one workflow_call to run build, test, and deploy in a single job.

Security

Pin smartcontractkit/.github/actions/setup-nodejs to commit hash (setup-nodejs@0.2.3) to satisfy CodeQL unpinned-action requirement.

Removed

actions/docs-test/ – Composite action removed; use reusable workflow instead.
actions/docs-deploy/ – Composite action removed; use reusable workflow instead.
.changeset/docs-actions-minor.md – No longer versioning the removed actions.

Other

pnpm-lock.yaml – Dropped actions/docs-test and actions/docs-deploy from lockfile.

Convert docs-test and docs-deploy composite actions to reusable workflows for consistency with other .github workflows.

github-actions · 2026-01-30T16:52:43Z

👋 sebawo, thanks for creating this pull request!

To help reviewers, please consider creating future PRs as drafts first. This allows you to self-review and make any final changes before notifying the team.

Once you're ready, you can mark it as "Ready for review" to request feedback. Thanks!

.github/workflows/reusable-docs-deploy.yml

.github/workflows/reusable-docs-test.yml

…cusaurus Single reusable workflow with two jobs: docs-test (build + test) and docs-deploy (build + deploy to GitHub Pages). Deploy runs after test succeeds. Remove reusable-docs-test.yml and reusable-docs-deploy.yml.

Pin smartcontractkit/.github/actions/setup-nodejs to commit hash (43fe7fd) to resolve CodeQL unpinned-action warning.

.github/workflows/reusable-docusaurus.yml

Co-authored-by: chainchad <96362174+chainchad@users.noreply.github.com>

chainchad · 2026-01-30T17:11:22Z

.github/workflows/reusable-docusaurus.yml

+        working-directory: ${{ inputs.docs-directory }}
+        env:
+          BUILD_COMMAND: ${{ inputs.build-command }}
+        run: $BUILD_COMMAND


I wonder if we should get rid of the first job, and just have one job since we have to build? We coudl run build and test in this job.

@chainchad good optimisation! fixed.

.github/workflows/reusable-docusaurus.yml

erikburt · 2026-01-30T18:41:03Z

.github/workflows/reusable-docusaurus.yml

+      id-token: write
+    steps:
+      - name: Checkout repo
+        if: inputs.checkout-repo == 'true'


This should not be optional. We have it in actions because the calling job may or may not checkout the repo before calling the action.

Because this is a self-contained reusable workfow, these jobs are standalone and require a checkout.

erikburt · 2026-01-30T18:41:50Z

.github/workflows/reusable-docusaurus.yml

+      checkout-repo:
+        description: "enable git checkout repo"
+        required: false
+        type: string
+        default: "true"
+      checkout-repo-fetch-depth:
+        description: "number of commits to fetch"
+        required: false
+        type: string
+        default: "0"


I think we can delete these inputs. Checkout is no longer optional, and fetch depth seems like an unnecessary complexity.

erikburt · 2026-01-30T18:44:06Z

.github/workflows/reusable-docusaurus.yml

+
+      - name: Build documentation
+        shell: bash
+        working-directory: ${{ inputs.docs-directory }}


Should this be in the docs directory or the package.json directory?

@sebawo - Based on the reference workflow, they use pnpm -C ./docs build at the root of the repository. But they are setting up the node/pnpm using the package-json-directory at ./docs.

Given that, we probably don't need a docs-directory input.

Remove actions/docs-test and actions/docs-deploy; Docusaurus build/test and deploy is now only via reusable-docusaurus.yml workflow. Remove docs-actions-minor changeset and update pnpm-lock.yaml.

Build once, then run test (if set), upload pages artifact, and deploy. Removes duplicate build and second job (docs-deploy).

Co-authored-by: chainchad <96362174+chainchad@users.noreply.github.com>

- reusable-docusaurus: add job-level permissions (contents, pages, id-token) and header comment documenting required permissions; no workflow-level perms - pull-request-main: add workflow-permissions-check job to fail when reusable workflows have non-empty workflow-level permissions

sebawo · 2026-02-02T13:48:18Z

.github/workflows/reusable-docusaurus.yml

+      - uses: actions/checkout@v6
+
+      - name: Setup nodejs
+        uses: smartcontractkit/.github/actions/setup-nodejs@setup-nodejs/v1


@chainchad we need to write the custom config to skip those findings for internal actions.

erikburt · 2026-02-02T22:35:31Z

.github/workflows/reusable-docusaurus.yml

+
+      - name: Build documentation
+        shell: bash
+        working-directory: ${{ inputs.docs-directory }}


@sebawo - Based on the reference workflow, they use pnpm -C ./docs build at the root of the repository. But they are setting up the node/pnpm using the package-json-directory at ./docs.

Given that, we probably don't need a docs-directory input.

erikburt · 2026-02-02T22:42:38Z

.github/workflows/reusable-docusaurus.yml

+      - name: Upload pages artifact
+        uses: actions/upload-pages-artifact@v4.0.0
+        with:
+          path: >-
+            ${{ inputs.docs-directory }}/${{ inputs.build-output-directory }}
+
+      - name: Deploy to GitHub Pages
+        uses: actions/deploy-pages@v4.0.5


This uploads and deploys everytime. Based on the reference workflow, we need a way to:

Test the build during PR events, and MQ events.

Build and deploy on pushes to main

erikburt · 2026-02-02T22:45:44Z

.github/workflows/reusable-docusaurus.yml

+      - name: Test documentation
+        if: inputs.test-command != ''
+        shell: bash
+        working-directory: ${{ inputs.docs-directory }}
+        env:
+          TEST_COMMAND: ${{ inputs.test-command }}
+        run: $TEST_COMMAND


Based on the reference workflow, there is no "test" step. The testing workflow builds the docs, and that's the validation. Is there other use-cases where there will be a dedicated test for the docs?

feat(workflows): add reusable docs-test and docs-deploy workflows

76ed36d

Convert docs-test and docs-deploy composite actions to reusable workflows for consistency with other .github workflows.

sebawo requested a review from a team as a code owner January 30, 2026 16:52

product-security-plaid-production bot requested a review from chainchad January 30, 2026 16:52

github-advanced-security bot found potential problems Jan 30, 2026

View reviewed changes

.github/workflows/reusable-docs-deploy.yml Fixed Show fixed Hide fixed

.github/workflows/reusable-docs-test.yml Fixed Show fixed Hide fixed

sebawo changed the title ~~feat(workflows): add reusable docs-test and docs-deploy workflows~~ feat(workflows): add reusable Docusaurus workflow Jan 30, 2026

fix(workflows): pin setup-nodejs ref in reusable-docusaurus

55d3740

Pin smartcontractkit/.github/actions/setup-nodejs to commit hash (43fe7fd) to resolve CodeQL unpinned-action warning.

chainchad requested changes Jan 30, 2026

View reviewed changes

.github/workflows/reusable-docusaurus.yml Outdated Show resolved Hide resolved

.github/workflows/reusable-docusaurus.yml Outdated Show resolved Hide resolved

Update .github/workflows/reusable-docusaurus.yml

090b262

Co-authored-by: chainchad <96362174+chainchad@users.noreply.github.com>

chainchad reviewed Jan 30, 2026

View reviewed changes

.github/workflows/reusable-docusaurus.yml Show resolved Hide resolved

chainchad previously approved these changes Jan 30, 2026

View reviewed changes

chainchad enabled auto-merge (squash) January 30, 2026 18:20

erikburt reviewed Jan 30, 2026

View reviewed changes

sebawo and others added 5 commits January 31, 2026 14:53

chore: remove docs-test and docs-deploy actions, keep workflow only

12e7481

Remove actions/docs-test and actions/docs-deploy; Docusaurus build/test and deploy is now only via reusable-docusaurus.yml workflow. Remove docs-actions-minor changeset and update pnpm-lock.yaml.

refactor(workflows): merge reusable-docusaurus into single job

6cf2e6a

Build once, then run test (if set), upload pages artifact, and deploy. Removes duplicate build and second job (docs-deploy).

Update .github/workflows/reusable-docusaurus.yml

3414b74

Co-authored-by: chainchad <96362174+chainchad@users.noreply.github.com>

Remove inputs and cleanup based on PR feedback

4575245

chainchad dismissed their stale review via 4575245 January 31, 2026 19:59

chainchad force-pushed the convert-docs-actions-to-reusable-workflows branch from e4a32e6 to 4575245 Compare January 31, 2026 19:59

github-advanced-security bot found potential problems Jan 31, 2026

View reviewed changes

sebawo changed the title ~~feat(workflows): add reusable Docusaurus workflow~~ feat(workflows): add reusable Docusaurus workflow (DX-2760) Feb 2, 2026

erikburt reviewed Feb 2, 2026

View reviewed changes

Conversation

sebawo commented Jan 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Changes

Added

Security

Removed

Other

Uh oh!

github-actions bot commented Jan 30, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Check warning

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

sebawo commented Jan 30, 2026 •

edited

Loading