Repository turn report

Fix docs mirroring to dirtydishes.github.io

The docs publishing workflow now mirrors the generated static docs payload into the actual GitHub Pages site repository, dirtydishes/dirtydishes.github.io, under the islandflow/docs/ path.

May 31, 2026Beads: islandflow-m3dWorkflow: .github/workflows/docs-pages.yml

Summary

Repaired the Pages publishing target so repository docs are copied to dirtydishes.github.io/islandflow/docs/ instead of attempting to force-push a gh-pages branch back to the mirrored islandflow repository.

Changes Made

Changed the workflow permission from write to read for the source repository, because publishing now happens through the target Pages checkout.
Added explicit Pages target settings for dirtydishes/dirtydishes.github.io, branch master, and prefix islandflow.
Added a target-repository checkout that uses secrets.DOCS_PAGES_TOKEN.
Mirrors the static payload into pages/islandflow/, which serves the docs at /islandflow/docs/.
Commits and pushes only when the generated mirror content actually changed.
Deletes .DS_Store files from the generated site payload before publishing.
Tightened the docs index generator so regenerated HTML does not introduce trailing whitespace.
Regenerated docs/index.html so the docs index reflects the current repository docs set.
Manually published the current docs snapshot to dirtydishes/dirtydishes.github.io while the automated mirror path awaits secret verification.

Context

The previous workflow built a valid static payload, but its publish step initialized a temporary Git repository and pushed gh-pages to github.com/$GITHUB_REPOSITORY. That targets the dirtydishes/islandflow mirror, not the user Pages repository that serves dirtydishes.github.io.

Cross-repository publishing cannot rely on the default GITHUB_TOKEN from the source workflow. The fixed workflow uses a dedicated secret token for the Pages site checkout and push.

Important Implementation Details

The public URL remains https://dirtydishes.github.io/islandflow/docs/.
The target repository branch is master, matching the current remote state of dirtydishes/dirtydishes.github.io.
The workflow removes and replaces only the islandflow/ subtree in the Pages repository, leaving any other site content alone.
The workflow requires a GitHub Actions secret named DOCS_PAGES_TOKEN with permission to read and write dirtydishes/dirtydishes.github.io.

Relevant Diff Snippets

Rendered with @pierre/diffs/ssr using server-side generated markup so this report is readable offline without loading remote JavaScript.

.github/workflows/docs-pages.yml

-13+32

10 unmodified lines
11
12
13
14
15
16
17
2 unmodified lines
20
21
22
23
24
25
3 unmodified lines
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
10 unmodified lines
  workflow_dispatch:

permissions:
  contents: write

concurrency:
  group: "docs-pages"
2 unmodified lines
jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v5
3 unmodified lines

      - name: Prepare static site payload
        run: |
          mkdir -p site/docs
          cp -R docs/. site/docs/
          printf '%s\n' '<!doctype html><meta charset="utf-8"><meta http-equiv="refresh" content="0; url=https://dirtydishes.github.io/islandflow/docs/"><title>Islandflow Docs</title><a href="https://dirtydishes.github.io/islandflow/docs/">Continue to docs</a>' > site/index.html
          touch site/.nojekyll

      - name: Publish to gh-pages branch
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          set -euo pipefail
          rm -rf .gh-pages-tmp
          mkdir .gh-pages-tmp
          cp -R site/. .gh-pages-tmp/
          cd .gh-pages-tmp

          git init
          git checkout -b gh-pages
          git config user.name "github-actions[bot]"
          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
          git add -A
          git commit -m "publish docs from ${GITHUB_SHA}"

          git push --force "https://x-access-token:${GITHUB_TOKEN}@github.com/${GITHUB_REPOSITORY}.git" gh-pages:gh-pages
10 unmodified lines
11
12
13
14
15
16
17
2 unmodified lines
20
21
22
23
24
25
26
27
28
29
3 unmodified lines
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
10 unmodified lines
  workflow_dispatch:

permissions:
  contents: read

concurrency:
  group: "docs-pages"
2 unmodified lines
jobs:
  publish:
    runs-on: ubuntu-latest
    env:
      PAGES_REPOSITORY: dirtydishes/dirtydishes.github.io
      PAGES_BRANCH: master
      PAGES_PREFIX: islandflow
    steps:
      - name: Checkout
        uses: actions/checkout@v5
3 unmodified lines

      - name: Prepare static site payload
        run: |
          rm -rf site
          mkdir -p site/docs
          cp -R docs/. site/docs/
          printf '%s\n' '<!doctype html><meta charset="utf-8"><meta http-equiv="refresh" content="0; url=https://dirtydishes.github.io/islandflow/docs/"><title>Islandflow Docs</title><a href="https://dirtydishes.github.io/islandflow/docs/">Continue to docs</a>' > site/index.html
          touch site/.nojekyll

      - name: Checkout GitHub Pages site
        uses: actions/checkout@v5
        with:
          repository: ${{ env.PAGES_REPOSITORY }}
          ref: ${{ env.PAGES_BRANCH }}
          token: ${{ secrets.DOCS_PAGES_TOKEN }}
          path: pages
          fetch-depth: 0

      - name: Mirror docs into Pages site
        run: |
          set -euo pipefail
          rm -rf "pages/${PAGES_PREFIX}"
          mkdir -p "pages/${PAGES_PREFIX}"
          cp -R site/. "pages/${PAGES_PREFIX}/"
          touch pages/.nojekyll

      - name: Commit and push Pages mirror
        run: |
          set -euo pipefail
          cd pages
          git config user.name "github-actions[bot]"
          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
          git add "${PAGES_PREFIX}" .nojekyll

          if git diff --cached --quiet; then
            echo "No docs changes to publish."
            exit 0
          fi

          git commit -m "publish islandflow docs from ${GITHUB_SHA}"
          git push origin "HEAD:${PAGES_BRANCH}"

scripts/generate-docs-index.mjs

-8+4

128 unmodified lines
129
130
131
132
133
134
135
136
2 unmodified lines
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
128 unmodified lines
        .map((entry) => {
          const extension = path.extname(entry.relativePath).replace(".", "") || "file";
          const searchable = `${entry.relativePath} ${category}`.toLowerCase();
          return `
            <li class="doc-item" data-search="${escapeHtml(searchable)}">
              <a class="doc-link" href="${docsHref(entry.relativePath)}">${escapeHtml(
                entry.relativePath
              )}</a>
2 unmodified lines
                <span>${escapeHtml(formatBytes(entry.sizeBytes))}</span>
                <span>${escapeHtml(dateFormatter.format(entry.modifiedAt))}</span>
              </div>
            </li>
          `;
        })
        .join("\n");

      return `
        <section class="group" id="category-${escapeHtml(category)}">
          <h2>${escapeHtml(category)} <span>${entries.length}</span></h2>
          <ul class="doc-list">
            ${entryMarkup}
          </ul>
        </section>
      `;
    })
    .join("\n");

128 unmodified lines
129
130
131
132
133
134
135
2 unmodified lines
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
128 unmodified lines
        .map((entry) => {
          const extension = path.extname(entry.relativePath).replace(".", "") || "file";
          const searchable = `${entry.relativePath} ${category}`.toLowerCase();
          return `            <li class="doc-item" data-search="${escapeHtml(searchable)}">
              <a class="doc-link" href="${docsHref(entry.relativePath)}">${escapeHtml(
                entry.relativePath
              )}</a>
2 unmodified lines
                <span>${escapeHtml(formatBytes(entry.sizeBytes))}</span>
                <span>${escapeHtml(dateFormatter.format(entry.modifiedAt))}</span>
              </div>
            </li>`;
        })
        .join("\n");

      return `        <section class="group" id="category-${escapeHtml(category)}">
          <h2>${escapeHtml(category)} <span>${entries.length}</span></h2>
          <ul class="doc-list">
            ${entryMarkup}
          </ul>
        </section>`;
    })
    .join("\n");

Expected Impact for End-Users

Readers can browse the Islandflow docs at dirtydishes.github.io/islandflow/docs/ from the actual Pages site. Once DOCS_PAGES_TOKEN is configured, future updates should arrive through the automated mirror workflow instead of manual publication.

Validation

Passed: Ran node scripts/generate-docs-index.mjs; it generated docs/index.html with 65 entries.
Passed: Ran node --check scripts/generate-docs-index.mjs.
Passed: Parsed .github/workflows/docs-pages.yml with Ruby YAML.
Passed: Ran git diff --check after tightening the generated index output.
Passed: Published islandflow/docs to dirtydishes/dirtydishes.github.io and confirmed https://dirtydishes.github.io/islandflow/docs/ returns HTTP 200 with the docs index.
Not completed: bunx actionlint .github/workflows/docs-pages.yml still failed because the package did not expose a runnable executable in this environment.

Issues, Limitations, and Mitigations

The automated workflow will fail until DOCS_PAGES_TOKEN exists in the GitHub mirror repository secrets and can push to dirtydishes/dirtydishes.github.io.
The live site is currently repaired by a direct Pages repository publish; the workflow still needs a real GitHub Actions run after secret verification.
The docs index includes file modified timestamps, so regenerating it can change ordering and metadata when local mtimes differ from the committed version.

Follow-up Work

islandflow-8a6: Add or verify DOCS_PAGES_TOKEN in the GitHub mirror repository secrets, then manually run the Publish Docs workflow after this branch lands on the mirrored main.
Consider replacing timestamp-based docs index ordering with commit dates or filenames so generated output is less sensitive to local filesystem mtimes.