Written in full, but still a draft. Check commands and screenshots against the repo before the cohort starts.
Activity: Ship a change through the factory
The activity
You work in your own fork of the repo. You will take one tiny change from your computer to a green pull request, pass through every gate on the way, and watch one gate stop you on purpose. The change is small so that you can spend your attention on the gates, not the change.
The gates are described in Module 1 overview. The repo's own docs/factory.md is the source of truth for names and behavior.
Exercise 0: Set up your Mac
Time: 20 to 40 minutes, once
You need a Mac, the Terminal app, and a GitHub account that can see liatrio-labs/emerald-grove-hotels. You do not need Docker, Node or Maven. The project brings its own Maven (./mvnw).
-
Open Terminal (press
Cmd+Space, type "Terminal", press Return). Everything on this page is typed there. -
Install Apple's command line tools, which include Git. If they are already installed, it says so and you can move on:
xcode-select --install -
Install Homebrew, the Mac package manager. It may ask for your Mac password. Type it (nothing appears as you type) and press Return:
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"When it finishes, it prints a "Next steps" block with two or three commands. Copy and run each one, exactly as printed. Then close Terminal and open a new window.
-
Install Java 21, the pre-commit tool, and Go (two of the safety checks are built with it):
brew install --cask temurin@21
brew install pre-commit go -
Tell your Mac to use Java 21 for this project, then open a new Terminal window:
echo 'export JAVA_HOME=$(/usr/libexec/java_home -v 21)' >> ~/.zshrc -
Optional: the GitHub command line, which can fork and clone for you. The GitHub website works fine without it.
brew install gh
gh auth login -
Check everything:
java -version
git --version
pre-commit --version
You should see: java -version starts with openjdk version "21. The other two print a version number.
If not:
brew: command not found: you skipped the "Next steps" commands from step 3. Run them, then open a new Terminal window.java -versionshows a different number: open a new Terminal window. If it still does, run/usr/libexec/java_home -Vand tell your facilitator what it lists.- Any command asks for your Mac password: that is normal for installs. Type it and press Return.
- A command fails with a red error: copy the last few lines to your facilitator. Do not retry it ten times.
If a later step takes longer than the time shown, that is normal for the first run. Tools download things once. If it is far longer, or the output does not match what is described, stop and ask. Noticing where you got stuck is useful feedback.
Exercise 1: Get your copy
Time: 15 minutes
-
On GitHub, fork
liatrio-labs/emerald-grove-hotelsinto your own account (or the place your facilitator names). Leave "Copy themainbranch only" ticked. -
Clone your fork, not the original:
git clone https://github.com/<your-account>/emerald-grove-hotels.git
cd emerald-grove-hotels
git remote -v
ls -a
You should see: origin points at your account. The listing includes AGENTS.md, docs, .pre-commit-config.yaml and .github.
If you installed the GitHub command line, this does both steps in one go:
gh repo fork liatrio-labs/emerald-grove-hotels --clone
If not:
- If
.pre-commit-config.yamlis missing, tell your facilitator. The repo'smainshould already carry the factory. - If
originshowsliatrio-labs, you cloned the original. Clone your fork instead.
Exercise 2: Read the map
Time: 30 minutes
- Open
AGENTS.mdanddocs/factory.md. - In your own words, write one line per gate: what it looks for, and where it runs (your computer, the pull request, or after the merge).
- Ask your AI agent: "Explain each gate in docs/factory.md in one sentence." Compare its answer to your lines.
You should see: nine gates in docs/factory.md. Your lines and the agent's roughly agree.
Check yourself: find one thing the agent said that is not in the doc, or that the doc says differently. Which do you trust, and why?
Exercise 3: Run it
Time: 20 minutes
./mvnw verify
./mvnw spring-boot:run
Open http://localhost:8080 in a browser, look around, then stop the app with Ctrl+C.
You should see: BUILD SUCCESS from the first command. The app shows a hotel site with a home page, hotels and guests.
If not:
invalid target release: 21or a Java version error: your Java is older than 21. Redo Exercise 0, steps 4 and 5, then open a new Terminal window.Permission deniedon./mvnw: runchmod +x mvnw.- A long first run is normal: it downloads dependencies once.
Port 8080 was already in use: runPORT=8081 ./mvnw spring-boot:runand openhttp://localhost:8081.
Look at: target/site/jacoco/index.html. This is the 75% coverage gate's report. Why is that number a gate rather than a suggestion?
Exercise 4: Turn on the hooks
Time: 20 to 40 minutes, mostly waiting
pre-commit install
pre-commit run --all-files
You should see: every hook ends in Passed: the hygiene hooks, gitleaks, semgrep, the dependency SBOM step, and osv-scanner.
If not:
pre-commit: command not found: you skipped part of Exercise 0. Runbrew install pre-commit, then open a new Terminal window.- The first run downloads and builds several tools. It can take several minutes and look stuck. Let it finish.
osv-scanneror the SBOM step fails with a network error: your network may block the vulnerability database. Tell your facilitator.
Check yourself: these are the same checks the pull request will run later. Why run them on your computer first?
Exercise 5: Make a small change
Time: 20 minutes
-
Make a branch:
git checkout -b try-the-factory -
In
src/main/resources/templates/welcome.html, add one sentence to the paragraph that starts "Three properties across North Carolina". Do it by hand, or ask your agent: "Add one friendly sentence to that paragraph in welcome.html. Change nothing else. Show me the diff." -
Read the change:
git status
git diff
You should see: one file changed, one or two lines added. Nothing else.
If not: if the agent touched other files, revert them before moving on:
git checkout -- <the-other-file>
Reading the diff before you accept it is the skill here. Say out loud what each changed line does.
Exercise 6: Watch a gate fix things for you
Time: 15 minutes
-
Add a few spaces at the end of the sentence you wrote.
-
Commit:
git add -A
git commit -m "Add a sentence to the welcome page" -
The commit stops. Read the output, then add the file again and commit again:
git add -A
git commit -m "Add a sentence to the welcome page"
You should see: trim trailing whitespace reports Failed and says it modified a file. The second commit passes, and git log --oneline shows your commit.
Why: a hook fixed the file and then stopped the commit so you could see what it changed. That is a gate working as designed, not an error.
Time warning: each commit runs the full hook set. Expect it to take from several seconds up to a minute or two.
Exercise 7: Watch pre-commit block a fake secret
Time: 20 minutes
You will create a file that looks like a private key but is not one, try to commit it, and watch the commit get refused. Never push this file.
-
Create the fake key. This builds it in pieces so this page does not itself contain a key-shaped block:
H="-----BEGIN ""PRIVATE KEY-----"
F="-----END ""PRIVATE KEY-----"
printf '%s\n' "$H" "ZmFrZS1kZW1vLWtleS1ub3QtcmVhbC1ub3QtYS1zZWNyZXQ=" "$F" > fake-key-demo.pem
cat fake-key-demo.pem -
Try to commit it:
git add fake-key-demo.pem
git commit -m "Add a fake key (this should be blocked)" -
Read the output, then clean up:
git restore --staged fake-key-demo.pem
rm fake-key-demo.pem
git status
git log --oneline
You should see: detect private key reports Failed, and Detect hardcoded secrets (gitleaks) reports Failed with RuleID: private-key and the file name. After cleanup, git status shows nothing to commit and no new commit in the log.
If not: if both hooks pass, stop and tell your facilitator. Do not try other values. Only this key shape is known to be blocked.
Check yourself:
- At which gate did it stop, and where is that on the map? Is that the earliest or latest possible place?
- What would have caught it if hooks were off? (Hint: look at
Hygiene and secretsindocs/factory.md.) - Why do both hooks fire on one file? Is that wasteful or deliberate?
Exercise 8: Push and watch the pull request
Time: 30 minutes, mostly waiting
-
Push your branch to your fork:
git push -u origin try-the-factory -
Open a pull request. Choose your fork's
mainas the base, notliatrio-labs. GitHub defaults a fork's pull request to the original repo. In the page's base-repository dropdown pick your own repo. -
Open the Checks tab and watch.
You should see: six checks turn from yellow (running) to green (passed):
Build, test and coverageHygiene and secretsSemgrepOSV-ScannerTrivy filesystem scanTrivy image scan (Dockerfile.vercel)
You may also see extra code-scanning checks. They are not part of the six.
If not:
- No checks appear, with a message about workflows on a forked repo: open your fork's Actions tab and enable workflows.
- A check is red: open it, read the last 20 lines, fix, push again.
- Everything shows yellow for several minutes: normal.
OSV-Scannerand the image scan take the longest, around three or four minutes.
Exercise 9 (optional): Break something on purpose
Time: 20 minutes. For confident learners.
- Make a throwaway branch:
git checkout -b break-it. - In
src/test/java/org/liatrio/emeraldgrove/hotels/WebTests.java, change what thehomePagetest expects to a phrase that is not on the page. - Run
./mvnw verify. - Undo it:
git checkout -- ., thengit checkout try-the-factory, thengit branch -D break-it.
You should see: BUILD FAILURE and the name of the failing test. A pull request with this change would be blocked.
Exercise 10: Merge in your fork and read the deploy notice
Time: 10 minutes
- In your fork, merge your pull request.
- Open the Actions tab and open the Deploy run.
You should see: a grey or skipped Deploy with a notice listing the credentials your fork does not have. This is not a failure. It means the deploy gate exists and has been told to stand down without credentials.
Check yourself: why is a quiet skip a risk in a real project? How would you notice a deploy gate that had silently stopped working?
Exercise 11: Watch a real deploy (facilitator-led)
Time: 20 minutes. Led by your facilitator.
Your facilitator merges one change into the shared repo. A merge to main deploys to Vercel. Watch the Deploy and Smoke test jobs run in its Actions tab. Then open the app address they give you.
You should see: Deploy, then Smoke test, turn green. The smoke test checks that / and /actuator/health answer. The app address shows a Vercel sign-in page. Production on Vercel is protected by Vercel login, so you cannot open it without signing in.
Check yourself: what does a smoke test prove, and what does it not prove? What would you add to raise your confidence?
Exercise 12: Write up your journey
Time: 30 minutes
Write five lines:
- What was your change?
- Which gate fired, and what did it say?
- Which gate surprised you?
- What would you check next time before a gate had to?
- Where does your hacktory end and your factory begin for this repo? Defend it.
Keep it short enough that someone reads it in two minutes. This is your demo for the week.
Done when
- The pull request in your fork has six green checks
- You have a screenshot or copy of the blocked fake-key commit
- The fake key file is gone and was never pushed
- You have written up your journey
Common problems
| Symptom | Likely cause | What to do |
|---|---|---|
| Commit "fails" but the file changed | A hook fixed it | Add the file again, commit again |
| First commit takes minutes | Hook tools downloading | Wait; later commits are faster |
brew: command not found | Homebrew's "Next steps" were skipped | Run them, then open a new Terminal window |
Pull request targets liatrio-labs | GitHub's fork default | Change the base repository to your fork |
| No checks run in your fork | Actions disabled on forks | Enable workflows in the Actions tab |
| Java version error | Java older than 21, or the wrong one is first | Redo Exercise 0, steps 4 and 5; open a new Terminal window |