[module 8] Walk user through PAT and SSH auth setup on github #106

New Issue

2026-06-23T20:20:00-04:00

justin commented

2026-06-23 20:20:00 -04:00

Since we are focusing on Github for the tutorial. lets walk the student through the setup process for creating a PAT, step by step in the hands on lab guide. let's just link to a how to on setting up ssh based credentials as optional (explain pro's and con's of each)

Build scope (AI-ready)

Problem

Module 8's lab tells the learner they need "a personal access token (for HTTPS) or an SSH key added to your account" and to "Do it first," but never walks them through how. The lesson's "Getting a credential (the shape)" callout is deliberately host-generic ("treat these as the shape, not gospel"). For a learner whose first push is on GitHub (the module's stated worked example), that abstraction is the wall: authentication is failure mode #1 and the single most common first-push blocker. This issue adds a concrete, GitHub-specific PAT walkthrough to the lab, links the SSH path as an optional alternative, and gives a short pros/cons so the learner can choose deliberately.

Affected files / areas

modules/08-remotes-and-hosting/README.md — the only file that needs to change. Specifically:
- The Hands-on lab section (starts ~line 309). The "You'll need" block (~line 326-337) already says to set auth up first; add the concrete walkthrough as a new lab subsection before Part A (Part A starts ~line 339), or as a numbered pre-step inside Part A step 1 (~line 341-347).
- The Verify-before-publish checklist (~line 502-530) already has a generic "Credential/token UI" item (~line 527-529); extend it with the GitHub-specific PAT menu path, token type (fine-grained vs classic), and write-scope label, since these are volatile UI claims.
Do not rewrite the lesson's generic "Getting a credential (the shape)" callout (~line 139-156) or the "three failure modes" section (~line 123-173); those stay provider-neutral. The new content is GitHub-as-worked-example in the lab, not a forge change in the lesson.

Recommended approach

Add a lab subsection (e.g. ### Set up GitHub authentication (do this first)) between the "You'll need" block and Part A. It walks the PAT / HTTPS path step by step on GitHub as the worked example:
- Navigate GitHub Settings → Developer settings → Personal access tokens. Note GitHub offers two token types: fine-grained (recommended; scoped to the single tasks-app repo, with Contents: Read and write) and classic (the repo scope). Pick one and be explicit which the steps follow.
- Set an expiration, select repository access (fine-grained: just tasks-app), grant the write scope, generate, and copy the value once (it is shown a single time).
- At git's password prompt on first push, paste the token (terminal shows nothing while pasting — normal). Mention the credential helper caches it so it is pasted only once. This connects directly to failure mode #1 (the scope 403 gotcha already documented in the lesson).
- Mark the UI specifics with a Verify-before-publish note (menu names and scope labels drift).
SSH as the optional alternative (per the issue, link a how-to, do not write a full walkthrough): add a short bullet linking GitHub's official docs — "Generating a new SSH key and adding it to the ssh-agent", "Adding a new SSH key to your GitHub account", and "Connecting to GitHub with SSH". Mark it clearly optional.
Pros/cons of each (the issue asks for this explicitly). A compact comparison:
- PAT / HTTPS: + fast setup entirely in the web UI; works over port 443 through corporate proxies/firewalls. − expires and needs rotation; the write-scope gotcha (a token can auth then 403 on push); shown once; must be cached by a credential helper or re-pasted.
- SSH key: + no expiry/rotation by default; no password prompts after setup; no token scope to get wrong. − more upfront setup (keygen, ssh-agent, add the public key); private-key/passphrase management; port 22 is sometimes blocked on locked-down networks.
- A short note: "more setup once, less friction forever" for SSH vs "fast now, rotate later" for PAT — matching the existing line at ~line 100.

Keep the change small and within the module's existing voice and structure. External doc links are already used elsewhere in the course (e.g. git-scm.com, 12factor.net), so linking GitHub docs is consistent.

Acceptance criteria / how to verify

A new lab subsection walks PAT creation on GitHub step by step, placed before/within Part A so it precedes the first push.
SSH is covered as an optional path via a link to a GitHub how-to (not a full hand-written walkthrough).
A pros/cons comparison of PAT vs SSH is present.
The lesson stays provider-neutral: the generic "shape" callout, the three-failure-modes section, the self-hosted track, and the hosting comparison are unchanged in their neutrality (GitHub appears only as the explicit worked example, consistent with the module's existing framing and AGENTS.md "GitHub is the default, not the requirement").
The Verify-before-publish checklist gains an item covering the GitHub PAT UI path / token type / write-scope label.
Build + tests pass:
- bash tools/check.sh → check.sh: PASS (this enforces the no-em-dash guard and that ## Prerequisites, ## Hands-on lab, ## Where it breaks headings remain present).
- python3 tools/build_wiki.py --repo-root . --out /tmp/awc-wiki-build --web-base https://git.jpaul.io/justin/ai-workflow-course --branch main --host gitea renders without error (the CI "build" step).
- Manual: grep -nP '\x{2014}' modules/08-remotes-and-hosting/README.md returns nothing (no em-dash).

Target surface(s)

Course content only (Markdown). One file: modules/08-remotes-and-hosting/README.md. No code, no lab scripts (cli.py, tasks.py, verify-backup.sh) touched. The wiki is generated build output — do not hand-edit it.

Stop-lines

Do not turn the module GitHub-only. Add GitHub as the concrete worked example in the lab; keep the lesson, the self-hosted track, and the hosting comparison provider-neutral (AGENTS.md core promise).
Do not write a full SSH walkthrough. The issue says to link a how-to and mark it optional.
Do not delete or water down the existing generic "Getting a credential (the shape)" callout or the three-failure-modes content.
No em-dash characters anywhere (hard rule; tools/check.sh fails the build otherwise). Watch the banned-words list in AGENTS.md.
Do not write the dated/UI specifics from memory as permanent fact — mark them Verify-before-publish, matching how the rest of the module handles volatile claims.
Scope is this one module's README; do not edit other modules or reorder the dependency chain.

Since we are focusing on Github for the tutorial. lets walk the student through the setup process for creating a PAT, step by step in the hands on lab guide. let's just link to a how to on setting up ssh based credentials as optional (explain pro's and con's of each) --- ## Build scope (AI-ready) ### Problem Module 8's lab tells the learner they need "a personal access token (for HTTPS) or an SSH key added to your account" and to "Do it first," but never walks them through *how*. The lesson's "Getting a credential (the shape)" callout is deliberately host-generic ("treat these as the shape, not gospel"). For a learner whose first push is on GitHub (the module's stated worked example), that abstraction is the wall: authentication is failure mode #1 and the single most common first-push blocker. This issue adds a concrete, GitHub-specific PAT walkthrough to the lab, links the SSH path as an optional alternative, and gives a short pros/cons so the learner can choose deliberately. ### Affected files / areas - `modules/08-remotes-and-hosting/README.md` — the only file that needs to change. Specifically: - The **Hands-on lab** section (starts ~line 309). The "You'll need" block (~line 326-337) already says to set auth up first; add the concrete walkthrough as a new lab subsection **before Part A** (Part A starts ~line 339), or as a numbered pre-step inside Part A step 1 (~line 341-347). - The **Verify-before-publish** checklist (~line 502-530) already has a generic "Credential/token UI" item (~line 527-529); extend it with the GitHub-specific PAT menu path, token type (fine-grained vs classic), and write-scope label, since these are volatile UI claims. - Do **not** rewrite the lesson's generic "Getting a credential (the shape)" callout (~line 139-156) or the "three failure modes" section (~line 123-173); those stay provider-neutral. The new content is GitHub-as-worked-example in the *lab*, not a forge change in the *lesson*. ### Recommended approach 1. **Add a lab subsection** (e.g. `### Set up GitHub authentication (do this first)`) between the "You'll need" block and Part A. It walks the **PAT / HTTPS** path step by step on GitHub as the worked example: - Navigate GitHub **Settings → Developer settings → Personal access tokens**. Note GitHub offers two token types: **fine-grained** (recommended; scoped to the single `tasks-app` repo, with **Contents: Read and write**) and **classic** (the `repo` scope). Pick one and be explicit which the steps follow. - Set an expiration, select repository access (fine-grained: just `tasks-app`), grant the write scope, generate, and **copy the value once** (it is shown a single time). - At git's `password` prompt on first push, paste the token (terminal shows nothing while pasting — normal). Mention the credential helper caches it so it is pasted only once. This connects directly to failure mode #1 (the scope `403` gotcha already documented in the lesson). - Mark the UI specifics with a **Verify-before-publish** note (menu names and scope labels drift). 2. **SSH as the optional alternative** (per the issue, *link* a how-to, do not write a full walkthrough): add a short bullet linking GitHub's official docs — "Generating a new SSH key and adding it to the ssh-agent", "Adding a new SSH key to your GitHub account", and "Connecting to GitHub with SSH". Mark it clearly **optional**. 3. **Pros/cons of each** (the issue asks for this explicitly). A compact comparison: - **PAT / HTTPS:** + fast setup entirely in the web UI; works over port 443 through corporate proxies/firewalls. − expires and needs rotation; the write-scope gotcha (a token can auth then `403` on push); shown once; must be cached by a credential helper or re-pasted. - **SSH key:** + no expiry/rotation by default; no password prompts after setup; no token scope to get wrong. − more upfront setup (keygen, ssh-agent, add the public key); private-key/passphrase management; port 22 is sometimes blocked on locked-down networks. - A short note: "more setup once, less friction forever" for SSH vs "fast now, rotate later" for PAT — matching the existing line at ~line 100. Keep the change small and within the module's existing voice and structure. External doc links are already used elsewhere in the course (e.g. `git-scm.com`, `12factor.net`), so linking GitHub docs is consistent. ### Acceptance criteria / how to verify - A new lab subsection walks PAT creation on GitHub **step by step**, placed before/within Part A so it precedes the first push. - SSH is covered as an **optional** path via a link to a GitHub how-to (not a full hand-written walkthrough). - A **pros/cons** comparison of PAT vs SSH is present. - The lesson stays provider-neutral: the generic "shape" callout, the three-failure-modes section, the self-hosted track, and the hosting comparison are unchanged in their neutrality (GitHub appears only as the explicit *worked example*, consistent with the module's existing framing and AGENTS.md "GitHub is the default, not the requirement"). - The **Verify-before-publish** checklist gains an item covering the GitHub PAT UI path / token type / write-scope label. - Build + tests pass: - `bash tools/check.sh` → `check.sh: PASS` (this enforces the **no-em-dash** guard and that `## Prerequisites`, `## Hands-on lab`, `## Where it breaks` headings remain present). - `python3 tools/build_wiki.py --repo-root . --out /tmp/awc-wiki-build --web-base https://git.jpaul.io/justin/ai-workflow-course --branch main --host gitea` renders without error (the CI "build" step). - Manual: `grep -nP '\x{2014}' modules/08-remotes-and-hosting/README.md` returns nothing (no em-dash). ### Target surface(s) Course content only (Markdown). One file: `modules/08-remotes-and-hosting/README.md`. No code, no lab scripts (`cli.py`, `tasks.py`, `verify-backup.sh`) touched. The wiki is generated build output — do not hand-edit it. ### Stop-lines - **Do not turn the module GitHub-only.** Add GitHub as the concrete *worked example* in the lab; keep the lesson, the self-hosted track, and the hosting comparison provider-neutral (AGENTS.md core promise). - **Do not write a full SSH walkthrough.** The issue says to *link* a how-to and mark it optional. - **Do not delete or water down** the existing generic "Getting a credential (the shape)" callout or the three-failure-modes content. - **No em-dash characters** anywhere (hard rule; `tools/check.sh` fails the build otherwise). Watch the banned-words list in AGENTS.md. - **Do not write the dated/UI specifics from memory as permanent fact** — mark them Verify-before-publish, matching how the rest of the module handles volatile claims. - Scope is this one module's README; do not edit other modules or reorder the dependency chain.

justin added the autopilot label 2026-06-23 20:20:00 -04:00

claude added the ai-ready label 2026-06-23 20:22:20 -04:00

justin referenced this issue from a commit

2026-06-23 20:26:09 -04:00

Module 8: walk through GitHub PAT setup, link SSH as optional (#106)

justin referenced a pull request that will close this issue

2026-06-23 20:26:40 -04:00

Module 8: walk through GitHub PAT setup, link SSH as optional (#106) #107

claude closed this issue

2026-06-23 20:32:05 -04:00

claude removed the autopilot label 2026-06-23 20:32:05 -04:00

claude referenced this issue from a commit