
A First Look at Build
Deploy a Node.js app with Build, explore config, logs, scaling, and PostgreSQL from the CLI, then set up GitHub deploys, pipelines, and rollback.
Introduction
Build is a platform as a service for deploying applications and managing their infrastructure. In this Build CLI tutorial, we'll deploy a small Node.js app, then use the CLI to change its configuration, read logs, scale processes, and ship updates. An optional PostgreSQL add-on will demonstrate how Build connects managed services to a running app.
The application is a single Express server. Its job is to give us something working to deploy so we can explore Build's features.
After account activation and CLI login, the main walkthrough stays in the terminal. We'll finish with optional dashboard features: connecting GitHub, creating pipelines, enabling review apps, and restoring an earlier build.
What We'll Cover
- Install the tools
- Create the app
- Deploy with Git
- Explore Build features
- Optional: add a managed database
- Optional: explore dashboard features
- Clean up
Before You Start: Account and Costs
Create a Build account, complete any email verification, and wait for account activation if prompted. Choose the account and team you intend to use, then complete the required plan and payment setup before installing the CLI. This walkthrough uses paid resources.
Review Build's current pricing before continuing. At the time of this update, Hobby is listed at $9/month with 350 dyno-hours; Developer-plan add-ons are purchased individually. These are separate cost considerations:
| Resource | When this tutorial uses it |
|---|---|
| Account plan | Activated during signup; remains subscribed after resource cleanup. |
| App compute | Running the first web process, briefly scaling to two, and optionally running pipeline or review apps consumes compute capacity. |
| Optional PostgreSQL add-on | Provisioned only in the database section; remains allocated until destroyed. |
Check your selected plan's capacity and the add-on's current price. A dashboard estimate of monthly usage is not a receipt for money already charged. Check billing and usage in your account rather than adding dashboard figures together or assuming the database is included in the account plan. The cleanup section explains resource teardown and subscription management separately.
Install the Tools
Use a Bash or Zsh terminal. Get the tooling for your operating system from these official installation guides:
- Node.js 24 or newer, including npm.
- Git.
- curl.
- Build CLI.
You'll also need a text editor. The examples use nano to edit .env; you can open that file in your preferred editor instead.
Log in to Build; this opens a browser to authorize the CLI:
bld login
Confirm the signed-in account:
bld whoami
List the teams available to your account:
bld teams
The login flow also configures Git authentication, so the deployment below uses the app's HTTPS Git URL.
Create the App
Create a new project outside an existing Git repository. Use build-demo as the working directory for the remaining commands:
mkdir build-demo
cd build-demo
git init -b main
mkdir src
Create package.json in the project root. This enables ECMAScript modules, requires Node.js 24 or newer, and defines the start and syntax-check scripts:
{
"name": "build-demo",
"version": "1.0.0",
"private": true,
"type": "module",
"engines": {
"node": ">=24"
},
"scripts": {
"start": "node src/server.js",
"check": "node --check src/server.js"
}
}
Install Express:
npm install --save-exact express@5.3.0
Create src/server.js:
import express from "express";
const app = express();
app.get("/", (req, res) => {
console.log(`${req.method} ${req.path}`);
res.json({ message: process.env.APP_MESSAGE ?? "Hello from Build v1" });
});
app.get("/health", (req, res) => res.json({ ok: true }));
app.listen(Number(process.env.PORT ?? 3000), "0.0.0.0", () => {
console.log("App is listening");
});
Build supplies PORT at runtime. Listening on 0.0.0.0 lets its router reach the process. APP_MESSAGE gives us a config var to change after deployment.
Create .gitignore in the project root to keep dependencies, local settings, and generated files out of Git:
node_modules/
.env
.build-app.json
.build-addon.json
.build-check.mjs
Create Procfile alongside package.json to tell Build how to start the web process:
web: npm start
Check the source and start the app:
npm run check
npm start
In a second terminal, request the local app:
curl --fail-with-body -sS http://127.0.0.1:3000/
You should receive:
{"message":"Hello from Build v1"}
Stop the local server with Ctrl+C. Continue from build-demo to deploy it.
Deploy with Git
Commit the working app, including the generated lockfile. .gitignore keeps local settings and generated files out of the commit:
git add .
git commit -m "Create a small Build demo"
Save the deployment settings in .env. The commands below generate an app name and open the file in nano. Set TEAM to the exact team name shown by bld teams, keeping quotes around names that contain spaces. Save with Ctrl+O, press Enter, then exit with Ctrl+X. Review the printed team and app before creating this disposable app:
printf '%s\n' 'TEAM=""' > .env
node -p '"APP=build-demo-" + Date.now()' >> .env
nano .env
node --env-file=.env -e 'console.log({ team: process.env.TEAM, app: process.env.APP })'
Each command reads its saved values with Node's built-in --env-file=.env flag. For example, $(node --env-file=.env -p 'process.env.APP') supplies the app name directly to bld. Run these commands from build-demo; they need no exported variables or reload script. Node gives an already exported value precedence over the file, so use a fresh terminal if you previously exported these names. See the Node documentation for that behavior.
Create the app, record CREATED_APP only after creation succeeds, and save the actual app metadata. Keep CREATED_APP as the original creation record; cleanup uses it even if you later select other pipeline apps:
node --env-file=.env -e 'if (!process.env.TEAM?.trim() || !process.env.APP?.trim()) throw new Error("Set TEAM and APP in .env first")' &&
bld apps:create "$(node --env-file=.env -p 'process.env.APP')" \
-t "$(node --env-file=.env -p 'process.env.TEAM')" -r us-east-1 &&
node --env-file=.env -p '"CREATED_APP=" + process.env.APP' >> .env &&
bld apps:info -a "$(node --env-file=.env -p 'process.env.APP')" -j > .build-app.json
Build's default stack and language detection handle the Node.js application. The root package.json declares dependencies, and the Procfile declares the web process. See the deployment guide for those conventions.
Save the public HTTP URL and Git deployment URL returned by Build into .env:
node -e '
const app = require("./.build-app.json");
if (["web_url", "git_url"].some(key => typeof app[key] !== "string" || !app[key].trim())) throw new Error("Missing app URL or Git URL");
console.log("APP_URL=" + JSON.stringify(app.web_url.replace(/\/+$/, "")));
console.log("GIT_URL=" + JSON.stringify(app.git_url));
' >> .env
APP is the app name, APP_URL is its public HTTP address, and GIT_URL is its Git deployment endpoint. The Node command validates the metadata and removes the public URL's trailing slash before saving it, so later commands can append / or /db. The ignored JSON preserves the original metadata; subsequent commands read the values saved in .env. Save literal values in that file; Node does not expand references to other variables.
If app creation or metadata capture fails, inspect bld apps before retrying. To recover an existing app's URLs, rerun the apps:info metadata read and URL-saving command above; do not repeat app creation just to recover a value. When refreshing a saved value, update its existing line in .env rather than accumulating duplicate entries.
Verify Changes Before Continuing
Deployment and process commands can return before the requested state is visible. This reusable checker waits for three consecutive matching checks, makes at most two minutes of attempts, and limits each HTTP request or CLI read to five seconds.
Create .build-check.mjs in the build-demo project root, alongside package.json, and paste in this JavaScript:
import { execFileSync } from "node:child_process";
import { setTimeout as delay } from "node:timers/promises";
const [mode, target, expected] = process.argv.slice(2);
const modes = ["message", "database", "web", "addon", "removed"];
if (!modes.includes(mode) || !target ||
(["message", "web", "removed"].includes(mode) && expected === undefined) ||
(mode === "web" && (!Number.isInteger(Number(expected)) || Number(expected) < 0))) {
console.error("Usage: node .build-check.mjs <message|database|web|addon|removed> <URL|app|addon> [expected]");
process.exit(1);
}
const deadline = Date.now() + 120_000;
let consecutive = 0;
let result;
const readBld = (...args) => JSON.parse(execFileSync("bld", args, {
encoding: "utf8",
timeout: Math.max(1, Math.min(5000, deadline - Date.now())),
killSignal: "SIGKILL",
stdio: ["ignore", "pipe", "pipe"],
}));
while (Date.now() < deadline) {
let matches = false;
try {
if (mode === "message" || mode === "database") {
const response = await fetch(target, {
cache: "no-store",
signal: AbortSignal.timeout(Math.max(1, Math.min(5000, deadline - Date.now()))),
});
result = await response.json();
matches = response.ok && (mode === "message"
? result.message === expected
: typeof result.time === "string" && Number.isFinite(Date.parse(result.time)));
} else if (mode === "web") {
const groups = readBld("ps", "-a", target, "-j");
if (!Array.isArray(groups) || !groups.every(group =>
typeof group?.type === "string" && Number.isInteger(group.quantity) &&
group.quantity >= 0 && Array.isArray(group.processes))) throw new Error("Invalid process data");
const web = groups.filter(group => group.type === "web");
const processes = web.flatMap(group => group.processes);
matches = web.reduce((total, group) => total + group.quantity, 0) === Number(expected) &&
processes.length === Number(expected) &&
processes.every(process => process.status === "Running");
} else if (mode === "addon") {
matches = readBld("addons:info", target, "-j").state === "provisioned";
} else {
const addons = readBld("addons", "-a", target, "-j");
matches = Array.isArray(addons) && addons.every(addon =>
typeof addon?.id === "string" && typeof addon.state === "string") && addons.every(addon =>
addon.id !== expected || addon.state === "deprovisioned");
}
} catch {
// A failed request, CLI read, or JSON parse is an unmet check.
}
consecutive = matches ? consecutive + 1 : 0;
if (consecutive === 3) {
console.log(`Verified ${mode}: ${target}`);
if (mode === "message" || mode === "database") console.log(JSON.stringify(result));
process.exit(0);
}
console.log(`Waiting for ${mode}: ${target} (${consecutive}/3 matching checks)`);
await delay(Math.max(0, Math.min(5000, deadline - Date.now())));
}
console.error("Expected state was not verified within two minutes. Stop this step and inspect status and logs.");
process.exit(1);
A nonzero exit means the step is incomplete. Stop and use Troubleshooting before making another change; an agent should report the failed expectation. This two-minute limit is a tutorial checkpoint, not a promise about provisioning time. After inspecting a slow operation, rerun its check without repeating the resource-creation command.
Add the app's Git URL as a remote, then push:
git remote add build "$(node --env-file=.env -p 'process.env.GIT_URL')"
git push build main
Build's Git endpoint deploys its remote main branch. If your local branch has another name, use git push build HEAD:main. This direct Git deployment works without connecting a GitHub repository.
Ensure one web process is running:
bld ps:scale web=1 -a "$(node --env-file=.env -p 'process.env.APP')"
bld ps -a "$(node --env-file=.env -p 'process.env.APP')"
node .build-check.mjs web "$(node --env-file=.env -p 'process.env.APP')" 1
After the process check passes, verify the deployed greeting at the public URL saved in .env:
node .build-check.mjs message \
"$(node --env-file=.env -p 'process.env.APP_URL')/" 'Hello from Build v1'
Expect {"message":"Hello from Build v1"}. Inspect the build and deployment records as well:
bld builds -a "$(node --env-file=.env -p 'process.env.APP')"
bld deployments -a "$(node --env-file=.env -p 'process.env.APP')"
Confirm that the initial build succeeded and a deployment is current (*). Keep one web process throughout the configuration and update exercises; scaling comes afterward.
Explore Build Features
Change Configuration
Set the message through Build's config vars:
bld config:set APP_MESSAGE='Configured through Build' -a "$(node --env-file=.env -p 'process.env.APP')"
bld config:get APP_MESSAGE -a "$(node --env-file=.env -p 'process.env.APP')"
The config:get command should print Configured through Build. Build's documented configuration behavior is to restart dynos with the new values without redeploying. Verify the running application separately:
node .build-check.mjs web "$(node --env-file=.env -p 'process.env.APP')" 1 &&
node .build-check.mjs message "$(node --env-file=.env -p 'process.env.APP_URL')/" 'Configured through Build'
The same deployed code now returns:
{"message":"Configured through Build"}
If this check times out or responses alternate, the change has not been verified. Read bld ps -a "$(node --env-file=.env -p 'process.env.APP')" and bld logs -a "$(node --env-file=.env -p 'process.env.APP')" --count 100, then compare the saved value above with the hosted environment:
bld run --no-tty --exit-code -a "$(node --env-file=.env -p 'process.env.APP')" printenv APP_MESSAGE
Expect Configured through Build; empty output or a nonzero exit is a failed check. Inspect only this demo variable. A manually invoked restart does not prove that the config change restarted the app automatically. Avoid scaling or repeatedly redeploying to diagnose this step. You can continue reading logs or clean up if it remains unresolved; first remove and verify the override as shown in the update section before continuing with code changes.
Read Logs
Fetch recent output from the app:
bld logs -a "$(node --env-file=.env -p 'process.env.APP')" --count 100
Look for App is listening and the GET / entries written by our requests. To stream new output, use:
bld logs -a "$(node --env-file=.env -p 'process.env.APP')" --tail --process web
Make a request in your browser or another terminal to produce another entry. Ctrl+C stops the log viewer. Build's logs guide explains its application and build log sources.
Run a Command in the Hosted Environment
Start a temporary one-off process and read the message config var:
bld run --no-tty --exit-code -a "$(node --env-file=.env -p 'process.env.APP')" printenv APP_MESSAGE
It should print Configured through Build. The process uses the deployed app's environment, and --exit-code forwards its exit status. The current one-off command implementation supports Unix systems and connects through the region's SSH endpoint.
Deploy an Update and Inspect Its History
Remove the config override so the response uses the message in our source:
bld config:unset APP_MESSAGE -a "$(node --env-file=.env -p 'process.env.APP')"
bld config:get APP_MESSAGE -a "$(node --env-file=.env -p 'process.env.APP')" -j
node .build-check.mjs message "$(node --env-file=.env -p 'process.env.APP_URL')/" 'Hello from Build v1'
The config:get output should be {}, confirming the override is gone, and the running app should return v1. Verify both before editing the source; a lingering config override would hide the code change.
In src/server.js, change Hello from Build v1 to Hello from Build v2. Check, commit, and push the edit:
npm run check
git add .
git commit -m "Update the greeting"
git push build main
Inspect the build and deployment records:
bld builds -a "$(node --env-file=.env -p 'process.env.APP')"
bld deployments -a "$(node --env-file=.env -p 'process.env.APP')"
The CLI marks the current deployment with *. Confirm the new build succeeded, then verify one running process and the updated response:
node .build-check.mjs web "$(node --env-file=.env -p 'process.env.APP')" 1 &&
node .build-check.mjs message "$(node --env-file=.env -p 'process.env.APP_URL')/" 'Hello from Build v2'
Expect Hello from Build v2. To undo this particular demo edit while it is still the latest commit, revert it and push again:
git revert --no-edit HEAD
git push build main
bld builds -a "$(node --env-file=.env -p 'process.env.APP')"
bld deployments -a "$(node --env-file=.env -p 'process.env.APP')"
node .build-check.mjs message "$(node --env-file=.env -p 'process.env.APP_URL')/" 'Hello from Build v1'
The next deployment should return Hello from Build v1. This creates a new commit and rebuilds the reverted source.
Scale and Restart Processes
After the configuration and code-update checks pass, briefly run two copies of the web process. Each additional dyno consumes account capacity:
bld ps:scale web=2 -a "$(node --env-file=.env -p 'process.env.APP')"
bld ps -a "$(node --env-file=.env -p 'process.env.APP')"
node .build-check.mjs web "$(node --env-file=.env -p 'process.env.APP')" 2
Expect two running web processes. Restart them, verify their status, then return to one instance before continuing:
bld ps:restart web -a "$(node --env-file=.env -p 'process.env.APP')"
bld ps -a "$(node --env-file=.env -p 'process.env.APP')"
node .build-check.mjs web "$(node --env-file=.env -p 'process.env.APP')" 2
Check the recent startup or restart timestamps in bld ps -a "$(node --env-file=.env -p 'process.env.APP')" and bld logs -a "$(node --env-file=.env -p 'process.env.APP')"; a running-process count alone does not prove the restart occurred.
bld ps:scale web=1 -a "$(node --env-file=.env -p 'process.env.APP')"
bld ps -a "$(node --env-file=.env -p 'process.env.APP')"
node .build-check.mjs web "$(node --env-file=.env -p 'process.env.APP')" 1 &&
node .build-check.mjs message "$(node --env-file=.env -p 'process.env.APP_URL')/" 'Hello from Build v1'
Do not continue until only one running web process remains. A scale command returning no output is not confirmation that scaling has finished. See scaling and performance for process sizes and counts.
Optional: Add a Managed Database
The app is already deployed. We can now use a PostgreSQL add-on to demonstrate Build's managed services. We'll query the database's current time to confirm the connection. To skip this paid resource, continue to the dashboard exercises or finish and clean up.
Install the PostgreSQL client:
npm install --save-exact pg@8.23.1
Replace src/server.js with this version, which adds a /db endpoint:
import express from "express";
import pg from "pg";
const app = express();
const databaseUrlKey = process.env.DATABASE_URL_KEY ?? "DATABASE_URL";
const databaseUrl = process.env[databaseUrlKey];
const pool = databaseUrl
? new pg.Pool({ connectionString: databaseUrl, max: 2, connectionTimeoutMillis: 5000 })
: null;
pool?.on("error", () => console.error("Database connection failed"));
app.get("/", (req, res) => {
console.log(`${req.method} ${req.path}`);
res.json({ message: process.env.APP_MESSAGE ?? "Hello from Build v1" });
});
app.get("/health", (req, res) => res.json({ ok: true }));
app.get("/db", async (req, res) => {
if (!pool) return res.status(503).json({ error: "Attach a database first" });
try {
const { rows } = await pool.query("SELECT CURRENT_TIMESTAMP AS time");
res.json(rows[0]);
} catch {
res.status(503).json({ error: "Database unavailable" });
}
});
app.listen(Number(process.env.PORT ?? 3000), "0.0.0.0", () => {
console.log("App is listening");
});
The app still serves its greeting without a database. /health checks the web process; /db checks the optional database connection. DATABASE_URL_KEY will contain the name of the connection variable supplied by your add-on. The app reads the connection string from that named variable, with DATABASE_URL as a fallback. This avoids copying credentials into another config var or assuming every add-on uses the same name.
Commit and deploy the new endpoint:
npm run check
git add .
git commit -m "Add a database connection check"
git push build main
bld builds -a "$(node --env-file=.env -p 'process.env.APP')"
bld deployments -a "$(node --env-file=.env -p 'process.env.APP')"
node .build-check.mjs web "$(node --env-file=.env -p 'process.env.APP')" 1 &&
node .build-check.mjs message "$(node --env-file=.env -p 'process.env.APP_URL')/" 'Hello from Build v1'
Confirm the database-endpoint build succeeded and is current in the deployment list. The greeting alone does not prove that /db has been deployed.
Inspect the available add-on services and PostgreSQL plans:
bld addons:services
bld addons:plans schema-to-go
Review the current plans and the price printed by addons:plans. schema-to-go:basic is listed at $9/month at the time of this update; Developer-plan add-ons are purchased separately. It remains allocated until destroyed. Proceed only after accepting this paid resource; an agent should obtain authorization for it before running the next command. Provision it once and capture its ID:
bld addons:create schema-to-go:basic \
-a "$(node --env-file=.env -p 'process.env.APP')" -j > .build-addon.json &&
node -e '
const { id } = require("./.build-addon.json");
if (typeof id !== "string" || !id.trim()) throw new Error("Missing add-on ID");
console.log("ADDON_ID=" + JSON.stringify(id));
' >> .env &&
node .build-check.mjs addon "$(node --env-file=.env -p 'process.env.ADDON_ID')"
If creation returns an error or the saved JSON has no ID, inspect bld addons -a "$(node --env-file=.env -p 'process.env.APP')" before retrying; a request might have created a resource despite an interrupted response. Do not overwrite a saved add-on record by repeating creation. A provisioning timeout means inspect and rerun the check, not create a second database.
Once the add-on is provisioned, inspect it with the CLI. The output lists connection-variable names, without revealing their values:
bld addons:info "$(node --env-file=.env -p 'process.env.ADDON_ID')"
Use the PostgreSQL connection URL variable listed by the add-on. The add-on guide describes automatic config attachment, but the walkthrough received a provider-specific variable rather than the documented DATABASE_URL. Discover the actual name instead of guessing its spelling. If no connection-variable name is shown, list only the app's configuration variable names, then identify the connection URL using the add-on's documentation or dashboard:
bld config -a "$(node --env-file=.env -p 'process.env.APP')" -j |
node -e 'try { console.log(Object.keys(JSON.parse(require("node:fs").readFileSync(0, "utf8"))).join("\n")); } catch { process.exitCode = 1; }'
Open .env and add DATABASE_URL_KEY with that variable's exact name as its quoted value. Save and close the file. This is the connection-variable name listed by the add-on, not the connection string. Verify that the hosted variable has a value without printing the credentials, then tell the application which key to read:
(
set -e
set -o pipefail
nano .env
node --env-file=.env -e 'if (!process.env.DATABASE_URL_KEY?.trim()) throw new Error("Set DATABASE_URL_KEY in .env first")' &&
bld config:get "$(node --env-file=.env -p 'process.env.DATABASE_URL_KEY')" \
-a "$(node --env-file=.env -p 'process.env.APP')" -j |
node --env-file=.env -e '
try {
const config = JSON.parse(require("node:fs").readFileSync(0, "utf8"));
const value = config[process.env.DATABASE_URL_KEY];
process.exitCode = typeof value === "string" && value.length > 0 ? 0 : 1;
} catch {
process.exitCode = 1;
}
' &&
bld config:set \
"DATABASE_URL_KEY=$(node --env-file=.env -p 'process.env.DATABASE_URL_KEY')" \
-a "$(node --env-file=.env -p 'process.env.APP')"
)
If the presence check fails, stop and identify the correct connection variable before proceeding. DATABASE_URL_KEY stores a name such as the one you just inspected; it never stores the URL itself. Confirm the saved name and the deployed database query:
bld config:get DATABASE_URL_KEY -a "$(node --env-file=.env -p 'process.env.APP')"
node .build-check.mjs web "$(node --env-file=.env -p 'process.env.APP')" 1 &&
node .build-check.mjs database "$(node --env-file=.env -p 'process.env.APP_URL')/db"
The /db response contains the database server's current time, for example:
{"time":"2026-10-20T15:00:00.000Z"}
Your timestamp will differ. A successful /db check verifies that the deployed application can use the managed database. If it fails, check the current build, provisioning state, selected variable name, and runtime configuration using Troubleshooting. Do not infer success from a healthy / or /health response.
Keep the app and database available if you want to continue to the dashboard exercises. If you're finished, go to cleanup.
Optional: Explore Dashboard Features
We've deployed and operated the app, shipped an update, and optionally connected a managed database from the terminal. The following features need dashboard setup in CLI 1.1.143. Explore them while the app is running. Run cleanup only after your last optional exercise. You can also skip these exercises and clean up now.
Connect GitHub and Enable Automatic Deploys
Push this project to a GitHub repository you control. Open the app in the Build dashboard, then:
- Open Deploy, find Connection, select the GitHub organization and repository, and click Connect.
- Under Automatic Deploys, select the branch to deploy and click Enable Automatic Deploys.
Subsequent pushes to that GitHub branch trigger deployments. For a manual deployment, use Manual Deploy, select the branch, and click Deploy Branch. These GitHub deployment controls are an optional extension to the direct Git push workflow we already used.
If the repository has CI checks, the dashboard can also wait for them before deploying. Add your tests and an npm test script before enabling that gate.
Create a Pipeline and Promote a Build
A pipeline groups apps into stages. Use disposable demo apps for this exercise. If you already have a pipeline with demo apps, list the available apps, then add their actual names to .env as STAGING_APP and PRODUCTION_APP. Save literal app names, not references to other variables. Skip the creation block below when using existing apps. These selections are separate from the CREATED_APP and CREATED_PRODUCTION_APP cleanup records:
bld apps
nano .env
For a new pipeline, skip the existing-app block above. The first command below saves the tutorial app's actual name as STAGING_APP and generates PRODUCTION_APP. Creating the second app consumes additional compute when running; review your capacity before proceeding. Record CREATED_PRODUCTION_APP only if creation succeeds, and leave that ownership record unchanged when selecting pipeline targets later:
node --env-file=.env -p \
'"STAGING_APP=" + process.env.APP + "\nPRODUCTION_APP=build-prod-" + Date.now()' >> .env
node --env-file=.env -e 'if (!process.env.PRODUCTION_APP?.trim() || !process.env.TEAM?.trim()) throw new Error("Set PRODUCTION_APP and TEAM in .env first")' &&
bld apps:create "$(node --env-file=.env -p 'process.env.PRODUCTION_APP')" \
-t "$(node --env-file=.env -p 'process.env.TEAM')" -r us-east-1 &&
node --env-file=.env -p \
'"CREATED_PRODUCTION_APP=" + process.env.PRODUCTION_APP' >> .env
For a new pipeline, in the dashboard, choose New + → New Pipeline, name the pipeline, and assign these apps to its staging and production stages. If you use an existing pipeline, skip this step. Pipeline creation and stage assignment use the dashboard; the CLI can then inspect and promote the configured apps.
Compare the stages from the terminal:
bld pipelines:diff -a "$(node --env-file=.env -p 'process.env.STAGING_APP')"
Save the staging app's actual URL and request its current greeting. When nano opens, add STAGING_MESSAGE to .env with the expected greeting from the staging app's configuration or deployed source, such as STAGING_MESSAGE="Hello from Build v1" for this tutorial. Save and close the file. The remaining commands verify that greeting before promoting the build; a failed metadata read, request, or check stops the sequence.
(
set -e
set -o pipefail
bld apps:info -a "$(node --env-file=.env -p 'process.env.STAGING_APP')" -j |
node -e '
const { web_url } = JSON.parse(require("node:fs").readFileSync(0, "utf8"));
if (typeof web_url !== "string" || !web_url.trim()) throw new Error("Missing app public URL");
console.log("STAGING_URL=" + JSON.stringify(web_url.replace(/\/+$/, "")));
' >> .env
curl --fail-with-body -sS --connect-timeout 5 --max-time 5 \
"$(node --env-file=.env -p 'process.env.STAGING_URL')/"
nano .env
node --env-file=.env -e 'if (!process.env.STAGING_MESSAGE?.trim() || !process.env.PRODUCTION_APP?.trim()) throw new Error("Set STAGING_MESSAGE and PRODUCTION_APP in .env first")'
node .build-check.mjs message \
"$(node --env-file=.env -p 'process.env.STAGING_URL')/" \
"$(node --env-file=.env -p 'process.env.STAGING_MESSAGE')"
bld pipelines:promote \
-a "$(node --env-file=.env -p 'process.env.STAGING_APP')" \
--to "$(node --env-file=.env -p 'process.env.PRODUCTION_APP')"
bld deployments -a "$(node --env-file=.env -p 'process.env.PRODUCTION_APP')"
)
Ensure the target has a running web process and save its actual URL. Read its own APP_MESSAGE configuration, then add PRODUCTION_MESSAGE to .env with the expected greeting in quotes. Use its configured message when present, or the fallback greeting in the promoted source (Hello from Build v1 for this tutorial). Save and close the file before the checks run:
(
set -e
set -o pipefail
bld ps:scale web=1 -a "$(node --env-file=.env -p 'process.env.PRODUCTION_APP')"
bld apps:info -a "$(node --env-file=.env -p 'process.env.PRODUCTION_APP')" -j |
node -e '
const { web_url } = JSON.parse(require("node:fs").readFileSync(0, "utf8"));
if (typeof web_url !== "string" || !web_url.trim()) throw new Error("Missing app public URL");
console.log("PRODUCTION_URL=" + JSON.stringify(web_url.replace(/\/+$/, "")));
' >> .env
bld config:get APP_MESSAGE \
-a "$(node --env-file=.env -p 'process.env.PRODUCTION_APP')" -j
nano .env
node .build-check.mjs web \
"$(node --env-file=.env -p 'process.env.PRODUCTION_APP')" 1 &&
node .build-check.mjs message \
"$(node --env-file=.env -p 'process.env.PRODUCTION_URL')/" \
"$(node --env-file=.env -p 'process.env.PRODUCTION_MESSAGE')"
)
Promotion deploys the existing build artifact. The target keeps its own configuration and database; staging config vars and data aren't copied. Enter the target's own APP_MESSAGE if present, or the fallback greeting in the source being promoted (Hello from Build v1 for this tutorial). Confirm the intended deployment is current as well as checking its response. Leave an existing target's settings intact.
Enable Review Apps
After connecting the pipeline to your GitHub repository, open its settings to enable review apps. Configure their creation, cleanup, and environment variables there. Review apps give pull requests separate preview URLs and provision additional app resources.
Record the names of any review apps and add-ons created during this exercise. They are additional cleanup targets; the CREATED_APP and CREATED_PRODUCTION_APP entries in .env automatically track only the main app and a production app created by the block above.
Restore an Earlier Build
Open the tutorial app's Activity tab, find a previous successful build, and choose Rollback to here. This restores an earlier deployment artifact through the dashboard rollback workflow.
The git revert example earlier creates a new source commit and rebuilds it. Dashboard rollback selects an earlier build; your local Git history stays as it was. If you completed the optional database section, choose a build that includes /db when you want to keep that endpoint available.
After rollback, inspect bld deployments -a "$(node --env-file=.env -p 'process.env.APP')" and run the response check with the greeting from the build you selected. For example, if you restored the initial build:
node .build-check.mjs web "$(node --env-file=.env -p 'process.env.APP')" 1 &&
node .build-check.mjs message "$(node --env-file=.env -p 'process.env.APP_URL')/" 'Hello from Build v1'
After your last dashboard exercise, continue to cleanup below.
Clean Up
Finish or skip the optional dashboard exercises before running cleanup. If you enabled automatic deploys or review-app creation for the demo, disable those settings first so later pushes or pull requests do not recreate resources. List any review apps and add-ons you created alongside the main and production demo apps.
From build-demo, stop the web compute for apps created by this tutorial. These commands read CREATED_APP and the optional CREATED_PRODUCTION_APP from .env. Selecting an existing pipeline app does not add it to these ownership records. The production commands are skipped when no tutorial-created production app was recorded:
(
set -e
node --env-file=.env -e 'if (!process.env.CREATED_APP?.trim()) throw new Error("No tutorial app was recorded")'
bld ps:scale web=0 -a "$(node --env-file=.env -p 'process.env.CREATED_APP')"
bld ps -a "$(node --env-file=.env -p 'process.env.CREATED_APP')"
node .build-check.mjs web "$(node --env-file=.env -p 'process.env.CREATED_APP')" 0
if node --env-file=.env -e 'process.exit(process.env.CREATED_PRODUCTION_APP?.trim() ? 0 : 1)'; then
bld ps:scale web=0 \
-a "$(node --env-file=.env -p 'process.env.CREATED_PRODUCTION_APP')"
bld ps -a "$(node --env-file=.env -p 'process.env.CREATED_PRODUCTION_APP')"
node .build-check.mjs web \
"$(node --env-file=.env -p 'process.env.CREATED_PRODUCTION_APP')" 0
fi
)
Each check must confirm desired web quantity zero and no remaining web processes. If a check times out, inspect that app and repeat the check; cleanup is incomplete. After the app stops, its URL may return no healthy upstream. That is expected when there is no web process, but an HTTP error alone does not verify that compute or add-ons have been removed.
If you created the optional database, inspect the ADDON_ID saved in .env before deletion. The conditional skips this step when no add-on ID was recorded:
(
set -e
node --env-file=.env -e ''
if node --env-file=.env -e 'process.exit(process.env.ADDON_ID?.trim() ? 0 : 1)'; then
bld addons:info "$(node --env-file=.env -p 'process.env.ADDON_ID')"
fi
)
Confirm this is the disposable database created for this tutorial. Destruction permanently removes the database and its attachments. Then destroy it and verify removal using a successful add-on listing:
(
set -e
node --env-file=.env -e ''
if node --env-file=.env -e 'process.exit(process.env.ADDON_ID?.trim() ? 0 : 1)'; then
node --env-file=.env -e 'if (!process.env.CREATED_APP?.trim()) throw new Error("No tutorial app was recorded")' &&
bld addons:destroy "$(node --env-file=.env -p 'process.env.ADDON_ID')" \
-a "$(node --env-file=.env -p 'process.env.CREATED_APP')" &&
node .build-check.mjs removed \
"$(node --env-file=.env -p 'process.env.CREATED_APP')" \
"$(node --env-file=.env -p 'process.env.ADDON_ID')"
fi
)
The removal check passes only when the saved ID is absent or marked deprovisioned; a failed API request is not removal confirmation. Scaling web processes to zero leaves add-ons allocated until they are destroyed.
Finish in the Build dashboard:
- Open the team used for the tutorial. For each review app created during the optional exercise, inspect its resources, remove its disposable add-ons, and delete the app. Verify those resources disappear; do not rely solely on an automatic cleanup setting.
- Open each app recorded as
CREATED_APPorCREATED_PRODUCTION_APPin.env, go to Settings, and use the app deletion control. Confirm the exact app name when requested, then verify it no longer appears in the team's app list. CLI1.1.143has no app-delete command. Leave pre-existing pipeline apps in place. - Check the team's app and add-on inventories for remaining tutorial resources, including anything created during an interrupted request. Remove only resources you created for this walkthrough. Verify that no tutorial web processes or database add-ons remain; remove the optional demo pipeline after its demo apps are gone.
- Open Billing and review the remaining subscription separately. Resource teardown does not cancel the account plan or erase charges already incurred. If you opened the account only for this walkthrough and want to stop its recurring subscription, use the available subscription controls or contact Build support if cancellation is not exposed. Confirm the resulting subscription status before considering account cleanup complete.
Troubleshooting
| Symptom | Check |
|---|---|
| Login or Git push is rejected | Run bld whoami and confirm account activation and team access. |
| The build fails | Read bld logs -a "$(node --env-file=.env -p 'process.env.APP')" --source build and check the lockfile and start script. |
| The web process isn't ready | Inspect bld ps -a "$(node --env-file=.env -p 'process.env.APP')" and bld logs -a "$(node --env-file=.env -p 'process.env.APP')"; confirm the app uses PORT and 0.0.0.0. |
| The configured greeting doesn't appear | Compare bld config:get APP_MESSAGE -a "$(node --env-file=.env -p 'process.env.APP')" -j, the narrow hosted printenv APP_MESSAGE check, and the HTTP response. Keep one web process; stop the exercise if the expectation remains unmet. |
| The greeting alternates between values | Inspect process count, build and deployment records, and recent logs. A single matching request is insufficient; rerun the checker after investigating. |
| The greeting doesn't change after a push | Confirm the intended build succeeded and is current; check for an old APP_MESSAGE override. Verify its removal before testing the source greeting. |
/db returns 503 |
Check the current database-endpoint build, add-on provisioning state, and the exact connection key listed by the add-on. Inspect bld config:get DATABASE_URL_KEY -a "$(node --env-file=.env -p 'process.env.APP')"; verify the selected connection key is nonempty using the presence check above without printing its value. |
| A scale or restart command returns no output | Inspect bld ps -a "$(node --env-file=.env -p 'process.env.APP')" and run the web-count checker. For restarts, also inspect startup/restart timestamps and logs. |
| A provisioning or cleanup check times out | Inspect the saved resource ID and current status. Retry the read check after inspection; do not create another resource or treat an API error as proof of deletion. |
| A one-off command can't connect | Check the region's SSH host and port in bld apps:info -a "$(node --env-file=.env -p 'process.env.APP')" -j against your network's outbound rules. |
If you open a new terminal or switch agent sessions, return to the build-demo directory containing .env. Each command reads that file automatically. Inspect the saved app and its current metadata with:
bld apps:info -a "$(node --env-file=.env -p 'process.env.APP')" -j
The saved ADDON_ID, pipeline app names, URLs, expected greetings, and creation records remain in .env as you complete those exercises. .build-app.json and .build-addon.json preserve the original platform responses. If a URL has changed, refresh its existing .env entry from apps:info. Never rerun a creation block just to recover an identifier.
Verification Notes
The application examples were checked locally on macOS ARM64 with Node.js 26.12.0, npm 11.20.0, Express 5.3.0, and node-postgres 8.23.1. Checks covered initial and configured greetings, health, missing database configuration, provider-specific connection-key selection, the DATABASE_URL fallback, and safe query failures. Database query checks used a mocked connection pool. Shell examples were syntax-checked in Bash and Zsh.
The polling helper passed 29 local fixture cases covering successful and delayed responses, alternating values, request failures, malformed data, process counts, provisioning, removal, and timeouts. The .env capture, JSON processing, command substitution, and cleanup examples use Node's built-in modules. They were checked in Bash and Zsh with a stub CLI, including team names with spaces, existing pipeline apps, and failed operations. Hosted commands and dashboard steps were reviewed against Build's documentation and CLI 1.1.143; this revision has not been rerun against a live Build account.
Resources and Links
- Build documentation — platform concepts and guides.
- CLI installation and authentication — installation and login.
- Git deployment — push URLs and branch behavior.
- CLI command reference — app, process, config, and history commands.
- CLI source at v1.1.143 — command implementations checked for this walkthrough.
- Pipelines and GitHub integration — dashboard setup, promotion, review apps, and CI gates.
- Add-on provisioning — managed services and resource lifecycle.
- Build pricing — current platform plans and costs.
- Node environment-file support — read saved deployment values for each command.
- node-postgres documentation — connections, pooling, and queries.