Full-Stack Deployment with a Builder Agent

In this lab you will deploy a full MERN application to Render, but instead of hand-following a deployment guide, you will direct Claude Code, working in the AI as Builder role, to generate the deployment configuration (a Render Blueprint) and a GitHub Actions continuous integration workflow, while you act as the Engineering Manager who reviews every file at defined checkpoints before it ships. Infrastructure as code, automated pipelines, and disciplined review of AI-generated configuration are exactly how modern teams make deployments repeatable and safe.

Estimated time: 60 minutes

Scenario

Your team has successfully built a prototype for a new TaskMaster application using the MERN stack. The prototype exists on GitHub but has only ever been run on a local machine. The project manager wants to share it with a small group of stakeholders to gather early feedback, so it needs a live, publicly accessible URL on the free tier of a Platform-as-a-Service provider.

Engineering leadership has added two requirements beyond the original ask. First, the deployment must be reproducible: the service definitions live in a render.yaml Blueprint file in the repository, not in a series of dashboard clicks nobody can retrace. Second, every push to the main branch must run a continuous integration workflow that fails loudly when the build breaks. Your team is piloting agentic AI tools, so the Builder agent will generate both files and make any small code changes the deployment requires. Your job is to review its work at each checkpoint, keep every secret out of version control, and prove the result works end to end.

Roles in This Lab

• Claude Code (Builder): inspects the repository, makes the minimal code changes deployment requires, and generates render.yaml and .github/workflows/ci.yml.
• You (Engineering Manager): set boundaries in CLAUDE.md, review every git diff at two checkpoints, send the agent back with corrections, supply secrets only through the Render dashboard, verify the live application, and document your decisions in DEPLOYMENT_AUDIT.md.

At least once during this lab, at Checkpoint 1 or Checkpoint 2, you must send the agent back with a specific correction or a required improvement before approving. If a generated file is already correct, choose a required improvement instead. Good candidates: add a healthCheckPath for the backend service, pin the workflow to a specific Node LTS line, cache npm downloads in the workflow, or add a comment above each environment variable entry explaining where its value is set. Record whichever revision you request in DEPLOYMENT_AUDIT.md.

Assignment Resources

1. Starter Application: simple-mern on GitHub  (or a maintained equivalent designated by your instructor)
2. MongoDB Atlas: Cloud Database  (free account and cluster required)
3. Render: PaaS Hosting  (free account required)
4. Render Blueprints: Infrastructure as Code documentation 
5. GitHub Actions: Documentation 

Part 1: Set Up the Starter, the Database, and Your Accounts (about 10 minutes)

1. Fork the simple-mern repository (or the instructor-designated equivalent) to your own GitHub account, then clone your fork and open a terminal at the repository root.

2. The starter’s default branch is named master, while this lab (including the CI workflow triggers and every push command below) standardizes on main. Rename the branch and push it to your fork:

   git branch -M main
   git push -u origin main

   Then set main as the default branch of your fork (on GitHub, open your fork’s settings and change the default branch) so that pull requests, the Actions tab, and Render all use it.

3. Create a free-tier cluster on MongoDB Atlas:

   • Create a database user with a password.
   • Under network access, allow access from anywhere (0.0.0.0/0) so Render’s free instances can connect.
   • Copy the connection string (it begins with mongodb+srv://).
   Caution

   Never paste the connection string into any file in the repository, into a prompt, or into render.yaml. It will be entered only in the Render dashboard in Part 4. Committing a database credential to a public repository is a serious security incident in a professional setting.

4. Create a free Render account at https://render.com  and connect it to your GitHub account when prompted.

5. Create CLAUDE.md at the repository root. Claude Code reads this file at the start of every session, which makes it the reliable place to enforce the Builder role and its boundaries:

   CLAUDE.md

   # TaskMaster Deployment Project Instructions
    
   You are acting as the Builder agent for this deployment project. The human
   developer is your Engineering Manager and reviews every change at a
   checkpoint before it ships.
    
   ## Boundaries
    
   - Never write secret values (connection strings, API keys, tokens) into
     any file in this repository. Secrets are declared with `sync: false` in
     render.yaml and set only in the Render dashboard.
   - Do not delete or rewrite application features. Make the smallest code
     changes needed for the deployment to work.
   - Explain every file you create or change so the Engineering Manager can
     review it against the checkpoint checklist.

6. Commit the instructions file:

   git add CLAUDE.md
   git commit -m "chore: add Builder agent instructions"

Part 2: Builder Phase 1, Deployment Configuration (about 15 minutes)

1. Install Claude Code if you have not already (Node.js 18 or later is required):

   npm install -g @anthropic-ai/claude-code

2. From the repository root, start Claude Code and log in with your Per Scholas-provided Claude account when prompted:

   claude

   If you are not logged in, run /login inside the session.

3. Paste the following directive:

   Inspect this repository and report its layout: where the Express server
   lives, where the React client lives, how the client reaches the API, and
   how each part is built and started.
   
   Then, acting as the Builder, prepare the project for deployment on Render:
   
   1. If the client reaches the API through a hardcoded localhost URL or a
      development proxy, change it to read the API base URL from a build-time
      environment variable, and tell me the exact variable name you used.
   2. Ensure the server reads its port from process.env.PORT, reads the
      MongoDB connection string from an environment variable named
      MONGODB_URI, and allows CORS requests from the origin named in a
      CLIENT_ORIGIN environment variable.
   3. Generate render.yaml at the repository root defining two services:
      - A Node web service for the backend: the correct root directory,
        build command, and start command for this repository's actual
        layout, with NODE_ENV=production set, and with MONGODB_URI and
        CLIENT_ORIGIN declared with sync: false so no secret or
        deploy-specific value is committed.
      - A static site for the frontend: the correct build command and
        publish directory for this repository's actual layout, a rewrite
        rule sending all paths to index.html, and the client's API base URL
        variable declared with sync: false.
   
   Do not put any real URLs or secrets in render.yaml. List every file you
   created or changed and why.

4. Claude Code asks permission before editing files or running commands. Read each request and approve deliberately.

5. Engineering Manager Checkpoint 1. New files do not appear in a plain git diff, so stage everything first and review the staged diff (or use the Source Control panel in VS Code):

   git add -A
   git diff --staged

   Review against this checklist:

   • render.yaml defines exactly two services: a Node web service and a static site.
   • The build, start, and publish settings match the repository’s actual directories and scripts. Open both package.json files and confirm. If the agent used npm ci, confirm a package-lock.json actually exists in that directory; otherwise have it use npm install.
   • No secret or account-specific value appears anywhere in the file. MONGODB_URI, CLIENT_ORIGIN, and the client’s API base URL variable are declared with sync: false.
   • A rewrite rule sends all frontend paths to index.html so client-side routing works.
   • The code changes are minimal and understandable, and no hardcoded localhost URL remains in the client’s production code path.
   • The field names match the current Render Blueprint documentation , since the format evolves over time.

   For orientation only, a Blueprint for a repository with server and client directories commonly resembles the shape below. Your file must match your repository and the current documentation, not this sample:

   services:
     - type: web
       name: taskmaster-api
       runtime: node
       rootDir: server
       buildCommand: npm install
       startCommand: npm start
       envVars:
         - key: NODE_ENV
           value: production
         - key: MONGODB_URI
           sync: false
         - key: CLIENT_ORIGIN
           sync: false
     - type: web
       name: taskmaster-client
       runtime: static
       rootDir: client
       buildCommand: npm install && npm run build
       staticPublishPath: ./build
       routes:
         - type: rewrite
           source: /*
           destination: /index.html
       envVars:
         - key: REACT_APP_API_URL
           sync: false

6. Approve, or send the agent back with specific corrections: quote the line that is wrong and state what it should do instead. Repeat the review until the checklist passes, then commit:

   git commit -m "feat: AI-generated Render Blueprint (reviewed)"

Part 3: Builder Phase 2, the CI Workflow (about 15 minutes)

1. In the same Claude Code session, paste the second directive:

   Acting as the Builder, generate .github/workflows/ci.yml for this
   repository:
   
   - Trigger on every push and every pull request to the main branch.
   - Check out the code and set up an actively supported Node LTS version
     that can build this project.
   - Install dependencies and run the production build for the client, and
     install dependencies for the server, using the correct working
     directories.
   - Run any test script that exists. If a build or test fails, the workflow
     run must fail.
   
   Do not add deployment steps; Render deploys from the repository directly.
   Explain each job and step so I can review it.

2. Engineering Manager Checkpoint 2. Stage and review the diff as before, against this checklist:

   • The workflow triggers on both push and pull_request for the main branch.
   • The Node version is an actively supported LTS release that can build this project.
   • Install commands match reality: npm ci only where a package-lock.json exists, npm install otherwise.
   • Every working-directory value matches the repository layout.
   • No secrets appear in the workflow, and no step suppresses failures (no continue-on-error and no ignored exit codes), so a broken build turns the run red.

   For orientation only, a minimal workflow for this layout commonly resembles:

   name: CI
   on:
     push:
       branches: [main]
     pull_request:
       branches: [main]
   jobs:
     build:
       runs-on: ubuntu-latest
       steps:
         - uses: actions/checkout@v4
         - uses: actions/setup-node@v4
           with:
             node-version: 22
         - name: Install and build client
           working-directory: client
           run: |
             npm install
             npm run build
         - name: Install server
           working-directory: server
           run: npm install

   Note

   Older guides prune development dependencies with npm install --production. That flag is deprecated in modern npm; the current equivalent is npm install --omit=dev. In this lab, Render’s build commands handle production installs, so you should not need either flag.

3. Approve (or send back corrections), commit, and push:

   git commit -m "feat: AI-generated CI workflow (reviewed)"
   git push origin main

4. Open your repository on GitHub and watch the run under the Actions tab. If the run fails, which is likely on the first attempt with an older starter:

   1. Open the failing job and copy the relevant portion of the log.
   2. Paste it into Claude Code and direct the agent to diagnose and repair the workflow or the code, whichever is at fault.
   3. Review the new diff just as you did at the checkpoints, then commit and push again.
   4. Repeat until the run is green. Record each cycle briefly in DEPLOYMENT_AUDIT.md.

Part 4: Deploy and Verify on Render (about 15 minutes)

1. In the Render dashboard, create a new Blueprint and select your forked repository. Render reads render.yaml and lists the two services it will create.

2. When Render prompts for the environment variables declared with sync: false, enter the MongoDB Atlas connection string as the value of MONGODB_URI. For CLIENT_ORIGIN and the client’s API base URL variable, you may not know the final URLs yet; enter temporary placeholder values and correct them in the next step.

3. Apply the Blueprint and wait for the first deploys to finish. Then copy each service’s actual public URL from its dashboard page, and:

   • Set CLIENT_ORIGIN on the backend web service to the frontend static site’s URL.
   • Set the client’s API base URL variable on the static site to the backend web service’s URL.
   • Let Render redeploy (or trigger a redeploy of) both services so the corrected values take effect. The frontend variable is applied at build time, so the static site must rebuild.

4. Verify the live application end to end: open the frontend URL, create a task, and confirm it appears after a reload. Check your Atlas cluster’s collections to confirm the data is really persisting.

5. If the backend fails at runtime, open its logs in the Render dashboard, paste the error into Claude Code, and run the same repair-review-push loop you used in Part 3. Render redeploys automatically when you push to the connected branch.

Part 5: Write the Deployment Audit (about 5 minutes)

Create DEPLOYMENT_AUDIT.md at the repository root, fill it in, then commit and push:

# Deployment Audit: TaskMaster on Render
 
## Reviewer
 
Name and date.
 
## What the Agent Generated
 
Files and code changes, one line each.
 
## Checkpoint 1 Decisions (render.yaml)
 
What you approved, what you rejected or corrected, and why. Include the
required revision if you made it here.
 
## Checkpoint 2 Decisions (ci.yml)
 
Same. Include the required revision if you made it here.
 
## CI Repair Loop
 
If any Actions run failed: what failed, what you pasted to the agent, and
what it changed.
 
## Secret Handling
 
How the connection string and deploy-specific values were kept out of
version control.
 
## Evidence
 
- Green GitHub Actions run: paste the link
- Backend Web Service URL: paste the link
- Frontend Static Site URL: paste the link

git add DEPLOYMENT_AUDIT.md
git commit -m "docs: deployment audit"
git push origin main

Submission Guidelines

Submit the following on Canvas:

1. The link to your GitHub repository. It must contain the AI-generated render.yaml and .github/workflows/ci.yml, your CLAUDE.md, and DEPLOYMENT_AUDIT.md with a link to a green GitHub Actions run.
2. The live URL of your backend Web Service on Render.
3. The live URL of your frontend Static Site on Render.

Because free Render services spin down when idle and free instances can be suspended, the repository evidence (the green Actions run and the audit) protects your credit even if a live URL responds slowly at grading time. A submission whose URLs never worked, however, will not receive full credit, so verify both before submitting.

Grading Rubric

This lab is worth 30 points.