Skip to main content
v2 draft

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).

  1. Open Terminal (press Cmd+Space, type "Terminal", press Return). Everything on this page is typed there.

  2. 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
  3. 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.

  4. 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
  5. 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
  6. 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
  7. 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 -version shows a different number: open a new Terminal window. If it still does, run /usr/libexec/java_home -V and 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.
note

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

  1. On GitHub, fork liatrio-labs/emerald-grove-hotels into your own account (or the place your facilitator names). Leave "Copy the main branch only" ticked.

  2. 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.yaml is missing, tell your facilitator. The repo's main should already carry the factory.
  • If origin shows liatrio-labs, you cloned the original. Clone your fork instead.

Exercise 2: Read the map​

Time: 30 minutes

  1. Open AGENTS.md and docs/factory.md.
  2. 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).
  3. 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: 21 or a Java version error: your Java is older than 21. Redo Exercise 0, steps 4 and 5, then open a new Terminal window.
  • Permission denied on ./mvnw: run chmod +x mvnw.
  • A long first run is normal: it downloads dependencies once.
  • Port 8080 was already in use: run PORT=8081 ./mvnw spring-boot:run and open http://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. Run brew 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-scanner or 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

  1. Make a branch:

    git checkout -b try-the-factory
  2. 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."

  3. 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

  1. Add a few spaces at the end of the sentence you wrote.

  2. Commit:

    git add -A
    git commit -m "Add a sentence to the welcome page"
  3. 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.

  1. 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
  2. Try to commit it:

    git add fake-key-demo.pem
    git commit -m "Add a fake key (this should be blocked)"
  3. 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 secrets in docs/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

  1. Push your branch to your fork:

    git push -u origin try-the-factory
  2. Open a pull request. Choose your fork's main as the base, not liatrio-labs. GitHub defaults a fork's pull request to the original repo. In the page's base-repository dropdown pick your own repo.

  3. Open the Checks tab and watch.

You should see: six checks turn from yellow (running) to green (passed):

  1. Build, test and coverage
  2. Hygiene and secrets
  3. Semgrep
  4. OSV-Scanner
  5. Trivy filesystem scan
  6. Trivy 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-Scanner and the image scan take the longest, around three or four minutes.

Exercise 9 (optional): Break something on purpose​

Time: 20 minutes. For confident learners.

  1. Make a throwaway branch: git checkout -b break-it.
  2. In src/test/java/org/liatrio/emeraldgrove/hotels/WebTests.java, change what the homePage test expects to a phrase that is not on the page.
  3. Run ./mvnw verify.
  4. Undo it: git checkout -- ., then git checkout try-the-factory, then git 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

  1. In your fork, merge your pull request.
  2. 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:

  1. What was your change?
  2. Which gate fired, and what did it say?
  3. Which gate surprised you?
  4. What would you check next time before a gate had to?
  5. 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​

SymptomLikely causeWhat to do
Commit "fails" but the file changedA hook fixed itAdd the file again, commit again
First commit takes minutesHook tools downloadingWait; later commits are faster
brew: command not foundHomebrew's "Next steps" were skippedRun them, then open a new Terminal window
Pull request targets liatrio-labsGitHub's fork defaultChange the base repository to your fork
No checks run in your forkActions disabled on forksEnable workflows in the Actions tab
Java version errorJava older than 21, or the wrong one is firstRedo Exercise 0, steps 4 and 5; open a new Terminal window