---
phase: 13-switch-github-pages-deploy-to-actions-artifact-eliminate-gh-pages-branch
plan: 01
type: execute
wave: 1
depends_on: []
files_modified:
  - .github/workflows/docs.yml
autonomous: false
requirements: []

must_haves:
  truths:
    - "Docs deploy workflow uses actions/upload-pages-artifact + actions/deploy-pages (not mkdocs gh-deploy)"
    - "Workflow permissions are pages: write and id-token: write (not contents: write)"
    - "Workflow has an environment block for github-pages with a page_url output"
    - "GitHub Pages source is set to GitHub Actions in repo settings"
    - "gh-pages remote branch no longer exists"
  artifacts:
    - path: ".github/workflows/docs.yml"
      provides: "Updated Pages artifact deployment workflow"
      contains: "actions/upload-pages-artifact"
  key_links:
    - from: ".github/workflows/docs.yml"
      to: "GitHub Pages"
      via: "actions/deploy-pages"
      pattern: "deploy-pages"
---

<objective>
Replace the current `mkdocs gh-deploy --force` deploy strategy in `.github/workflows/docs.yml` with the official GitHub Pages artifact deployment pattern (`actions/upload-pages-artifact` + `actions/deploy-pages`). After the new workflow runs successfully, delete the `gh-pages` remote branch to eliminate the only non-trunk branch in the repository.

Purpose: The current workflow pushes to a `gh-pages` branch, which violates the project's trunk-based workflow discipline. The artifact-based approach eliminates that intermediate branch entirely.
Output: Updated `docs.yml` workflow file + deleted `gh-pages` remote branch.
</objective>

<execution_context>
@/Users/shparki/.claude/get-shit-done/workflows/execute-plan.md
@/Users/shparki/.claude/get-shit-done/templates/summary.md
</execution_context>

<context>
@.planning/PROJECT.md
@.planning/ROADMAP.md
@.planning/STATE.md

<interfaces>
<!-- Current docs.yml (to be replaced) — key facts for the executor -->
<!-- Source: .github/workflows/docs.yml (35 lines) -->

Current workflow facts:
- Trigger: push to `develop` + `workflow_dispatch` (KEEP)
- permissions: contents: write (REPLACE with pages: write + id-token: write)
- Python setup: actions/setup-python@v5, python-version: '3.x' (KEEP)
- pip install: mkdocs==1.6.1 mkdocs-shadcn==0.10.2 mkdocs-redirects==1.2.2 "mkdocstrings[python]>=1.0.3" (KEEP, pinned versions)
- checkout: actions/checkout@v4 with fetch-depth: 0 (KEEP)
- "Configure git identity" step: REMOVE (not needed for artifact deploy)
- "Deploy docs" step (mkdocs gh-deploy --force): REPLACE with build + upload + deploy

New steps to add:
- `mkdocs build` (produces site/ directory)
- `actions/upload-pages-artifact@v3` with path: site
- `actions/deploy-pages@v4` (captures page_url output)
</interfaces>
</context>

<tasks>

<task type="auto">
  <name>Task 1: Rewrite docs.yml for artifact-based Pages deployment</name>
  <files>.github/workflows/docs.yml</files>
  <action>
Replace the entire contents of `.github/workflows/docs.yml` with the following YAML. Do not modify any other files.

```yaml
name: Deploy Docs

on:
  push:
    branches: [develop]
  workflow_dispatch:

concurrency:
  group: pages
  cancel-in-progress: false

permissions:
  pages: write
  id-token: write

jobs:
  deploy:
    name: Deploy to GitHub Pages
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - name: Check out repository
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.x'

      - name: Install MkDocs dependencies
        run: pip install mkdocs==1.6.1 mkdocs-shadcn==0.10.2 mkdocs-redirects==1.2.2 "mkdocstrings[python]>=1.0.3"

      - name: Build docs
        run: mkdocs build

      - name: Upload Pages artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: site

      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4
```

Key changes from previous workflow:
- `permissions` changed from `contents: write` to `pages: write` + `id-token: write` (required by deploy-pages action)
- Added `concurrency` group `pages` with `cancel-in-progress: false` (prevents race conditions on overlapping pushes)
- Added `environment` block with `name: github-pages` and `url: ${{ steps.deployment.outputs.page_url }}` (required by deploy-pages; also surfaces the live URL in the Actions run summary)
- Removed "Configure git identity" step (no git push needed)
- Replaced `mkdocs gh-deploy --force` with three steps: `mkdocs build`, `upload-pages-artifact@v3`, `deploy-pages@v4`
  </action>
  <verify>
    <automated>grep -n "upload-pages-artifact\|deploy-pages\|pages: write\|id-token: write\|github-pages\|concurrency" /Users/shparki/Documents/Workspace/thatdev/ztlctl/.github/workflows/docs.yml</automated>
  </verify>
  <done>
docs.yml contains: `actions/upload-pages-artifact@v3`, `actions/deploy-pages@v4`, `pages: write`, `id-token: write`, `environment: github-pages`, and `concurrency: group: pages`. Does NOT contain `gh-deploy`, `contents: write`, or `git config user`.
  </done>
</task>

<task type="checkpoint:human-verify" gate="blocking">
  <name>Task 2: Verify Pages source setting and live deployment</name>
  <action>Human verification required — no automated action. User must change GitHub Pages source and confirm the workflow run succeeds.</action>
  <what-built>Updated docs.yml that uses artifact-based Pages deployment. The workflow file is on the feature branch but has not been triggered yet — it will run when the PR is merged to develop.</what-built>
  <how-to-verify>
    Before merging the PR:

    1. Go to https://github.com/ThatDevStudio/ztlctl/settings/pages
    2. Under "Build and deployment" > "Source", change the value from "Deploy from a branch" (gh-pages) to **"GitHub Actions"**
    3. Click Save
    4. Merge the PR to develop
    5. Go to https://github.com/ThatDevStudio/ztlctl/actions and watch the "Deploy Docs" workflow run
    6. Confirm the run completes successfully (green check) and the "Deploy to GitHub Pages" step shows a live URL
    7. Visit the live URL and confirm the docs site loads correctly
  </how-to-verify>
  <resume-signal>Type "approved" once the Pages source is set to GitHub Actions and the workflow run succeeds. Or describe any issues encountered.</resume-signal>
</task>

<task type="auto">
  <name>Task 3: Delete gh-pages remote branch</name>
  <files></files>
  <action>
After the user confirms the artifact deploy is working (checkpoint approved), delete the `gh-pages` remote branch:

```bash
git push origin --delete gh-pages
```

This is the primary goal of the phase — eliminating the only non-trunk branch. If the branch does not exist (already deleted or never existed in the remote), the command will return an error; that is acceptable — the goal is already achieved.

Do NOT delete any local branch named `gh-pages` if one exists (it would be stale anyway, but leave local cleanup to the user).
  </action>
  <verify>
    <automated>git ls-remote --heads origin gh-pages</automated>
  </verify>
  <done>`git ls-remote --heads origin gh-pages` returns empty output (branch no longer exists on remote).</done>
</task>

</tasks>

<verification>
After all tasks complete:
1. `grep "upload-pages-artifact" /Users/shparki/Documents/Workspace/thatdev/ztlctl/.github/workflows/docs.yml` — returns a match
2. `grep "gh-deploy" /Users/shparki/Documents/Workspace/thatdev/ztlctl/.github/workflows/docs.yml` — returns no match
3. `git ls-remote --heads origin gh-pages` — returns empty (branch deleted)
4. GitHub Pages settings show "GitHub Actions" as the source
5. Docs site is live and correct at the URL shown in the Actions run summary
</verification>

<success_criteria>
- docs.yml triggers `actions/deploy-pages` (not `mkdocs gh-deploy`)
- Permissions are `pages: write` + `id-token: write`
- `environment: github-pages` block present with page_url output
- `concurrency` group prevents overlapping deploys
- GitHub Pages source setting is "GitHub Actions"
- `gh-pages` remote branch does not exist
- Docs site is live and correct
</success_criteria>

<output>
After completion, create `.planning/phases/13-switch-github-pages-deploy-to-actions-artifact-eliminate-gh-pages-branch/13-01-SUMMARY.md`
</output>
