0
# Build Management
1

2
Commands for managing Percy builds, including waiting for completion, finalizing parallel builds, and reviewing build results. These commands provide control over the Percy build lifecycle and enable automation workflows.
3

4
## Capabilities
5

6
### Build Wait
7

8
Wait for a Percy build to complete processing and optionally exit with an error code if visual differences are found.
9

10
```bash { .api }
11
/**
12
 * Wait for build to finish processing
13
 * Polls Percy API until build completes, with configurable timeout and behavior
14
 * 
15
 * Usage: percy build wait
16
 * 
17
 * Options:
18
 *   --build, -b <build-id>        Specific build ID to wait for
19
 *   --project, -p <project>       Build project slug (alternative to build-id)
20
 *   --commit, -c <sha>            Build commit SHA (alternative to build-id)
21
 *   --timeout, -t <ms>            Timeout before exiting (default: 10 minutes)
22
 *   --interval, -i <ms>           Polling interval (default: 10 seconds)
23
 *   --fail-on-changes, -f         Exit with error code if visual diffs found
24
 *   --pass-if-approved            Don't fail if build is approved
25
 * 
26
 * Exit codes:
27
 *   0 - Build completed successfully (no diffs or approved)
28
 *   1 - General error (network, authentication, etc.)
29
 *   2 - Build has visual differences (with --fail-on-changes)
30
 */
31
percy build wait
32
```
33

34
**Usage Examples:**
35

36
```bash
37
# Wait for current build (uses PERCY_BUILD_ID)
38
percy build wait
39

40
# Wait for specific build
41
percy build wait --build build_12345
42

43
# Wait with timeout
44
percy build wait --timeout 300000  # 5 minutes
45

46
# Fail CI if visual differences found
47
percy build wait --fail-on-changes
48

49
# Wait but pass if build is approved
50
percy build wait --fail-on-changes --pass-if-approved
51

52
# Wait for build by project and commit
53
percy build wait --project my-app --commit abc123
54
```
55

56
### Build Finalize
57

58
Finalize all parallel builds for the current project. Used in parallel build workflows where multiple Percy processes run simultaneously.
59

60
```bash { .api }
61
/**
62
 * Finalize parallel builds
63
 * Marks all parallel build shards as complete and triggers final processing
64
 * Used when PERCY_PARALLEL_TOTAL is set for parallel builds
65
 * 
66
 * Usage: percy build finalize
67
 * 
68
 * Options:
69
 *   --all                         Finalize all builds (not just parallel)
70
 */
71
percy build finalize
72
```
73

74
**Usage Examples:**
75

76
```bash
77
# Finalize parallel builds (typical usage)
78
percy build finalize
79

80
# Finalize all builds
81
percy build finalize --all
82
```
83

84
### Build ID
85

86
Print the build ID from the local Percy process. Useful for scripting and automation.
87

88
```bash { .api }
89
/**
90
 * Print build ID from local Percy process
91
 * Outputs the current build identifier to stdout
92
 * 
93
 * Usage: percy build id
94
 * 
95
 * Output: Build ID string (e.g., "build_12345")
96
 */
97
percy build id
98
```
99

100
**Usage Examples:**
101

102
```bash
103
# Get current build ID
104
BUILD_ID=$(percy build id)
105
echo "Current build: $BUILD_ID"
106

107
# Use in scripts
108
percy start
109
PERCY_BUILD_ID=$(percy build id)
110
npm test
111
percy stop
112
echo "Build completed: $PERCY_BUILD_ID"
113
```
114

115
### Build Review Commands
116

117
Approve, reject, or delete builds using Percy's build review API. Requires authentication credentials.
118

119
```bash { .api }
120
/**
121
 * Approve a build
122
 * Marks all visual differences in the build as approved
123
 * 
124
 * Usage: percy build approve <build-id>
125
 * 
126
 * Arguments:
127
 *   build-id                      Build ID to approve (required)
128
 * 
129
 * Options:
130
 *   --username <username>         Authentication username (or BROWSERSTACK_USERNAME env var)
131
 *   --access-key <key>           Authentication access key (or BROWSERSTACK_ACCESS_KEY env var)
132
 */
133
percy build approve <build-id>
134

135
/**
136
 * Reject a build
137
 * Marks the build as rejected, indicating visual differences are not acceptable
138
 * 
139
 * Usage: percy build reject <build-id>
140
 * 
141
 * Arguments:
142
 *   build-id                      Build ID to reject (required)
143
 * 
144
 * Options:
145
 *   --username <username>         Authentication username (or BROWSERSTACK_USERNAME env var)
146
 *   --access-key <key>           Authentication access key (or BROWSERSTACK_ACCESS_KEY env var)
147
 */
148
percy build reject <build-id>
149

150
/**
151
 * Unapprove a build
152
 * Removes approval status from a previously approved build
153
 * 
154
 * Usage: percy build unapprove <build-id>
155
 * 
156
 * Arguments:
157
 *   build-id                      Build ID to unapprove (required)
158
 * 
159
 * Options:
160
 *   --username <username>         Authentication username (or BROWSERSTACK_USERNAME env var)
161
 *   --access-key <key>           Authentication access key (or BROWSERSTACK_ACCESS_KEY env var)
162
 */
163
percy build unapprove <build-id>
164

165
/**
166
 * Delete a build
167
 * Permanently removes a build and all its snapshots
168
 * 
169
 * Usage: percy build delete <build-id>
170
 * 
171
 * Arguments:
172
 *   build-id                      Build ID to delete (required)
173
 * 
174
 * Options:
175
 *   --username <username>         Authentication username (or BROWSERSTACK_USERNAME env var)
176
 *   --access-key <key>           Authentication access key (or BROWSERSTACK_ACCESS_KEY env var)
177
 */
178
percy build delete <build-id>
179
```
180

181
**Usage Examples:**
182

183
```bash
184
# Approve a build
185
percy build approve build_12345 --username admin --access-key secret123
186

187
# Reject a build with visual differences
188
percy build reject build_12345 --username reviewer --access-key secret123
189

190
# Remove approval from a build
191
percy build unapprove build_12345 --username admin --access-key secret123
192

193
# Delete a test build
194
percy build delete build_12345 --username admin --access-key secret123
195
```
196

197
## Integration Patterns
198

199
### CI/CD Workflows
200

201
#### Basic Build Wait
202

203
```bash
204
# In CI pipeline
205
percy exec -- npm test
206
percy build wait --fail-on-changes
207
```
208

209
#### Parallel Build Workflow
210

211
```bash
212
# Job 1 (Chrome tests)
213
PERCY_PARALLEL_TOTAL=3 percy exec -- npm run test:chrome
214

215
# Job 2 (Firefox tests)  
216
PERCY_PARALLEL_TOTAL=3 percy exec -- npm run test:firefox
217

218
# Job 3 (Safari tests)
219
PERCY_PARALLEL_TOTAL=3 percy exec -- npm run test:safari
220

221
# Finalization job (runs after all parallel jobs complete)
222
percy build finalize
223
percy build wait --fail-on-changes
224
```
225

226
#### Matrix Build Strategy
227

228
```yaml
229
# GitHub Actions example
230
strategy:
231
  matrix:
232
    browser: [chrome, firefox, safari]
233
    
234
steps:
235
  - name: Run tests
236
    env:
237
      PERCY_PARALLEL_TOTAL: 3
238
    run: percy exec -- npm run test:${{ matrix.browser }}
239
    
240
  - name: Finalize builds
241
    if: strategy.job-index == 0  # Only run on first job
242
    run: |
243
      percy build finalize
244
      percy build wait --fail-on-changes
245
```
246

247
### Build Review Automation
248

249
```bash
250
# Auto-approve builds on main branch
251
if [[ "$BRANCH" == "main" ]]; then
252
  BUILD_ID=$(percy build id)
253
  percy build wait
254
  percy build approve "$BUILD_ID" --username ci-bot --access-key "$PERCY_ACCESS_KEY"
255
fi
256

257
# Auto-reject builds with too many changes
258
percy build wait
259
if [[ $? -eq 2 ]]; then  # Visual differences found
260
  BUILD_ID=$(percy build id)
261
  percy build reject "$BUILD_ID" --username ci-bot --access-key "$PERCY_ACCESS_KEY"
262
fi
263
```
264

265
### Cleanup Automation
266

267
```bash
268
# Delete old test builds
269
for build_id in $(get_old_test_builds); do
270
  percy build delete "$build_id" --username cleanup-bot --access-key "$PERCY_ACCESS_KEY"
271
done
272
```
273

274
## Environment Variables
275

276
### Build Identification
277

278
```bash { .api }
279
PERCY_BUILD_ID                     # Current build identifier
280
PERCY_BUILD_URL                    # Percy dashboard URL for build
281
```
282

283
### Parallel Build Configuration
284

285
```bash { .api }
286
PERCY_PARALLEL_TOTAL               # Total number of parallel processes
287
PERCY_PARALLEL_NONCE               # Unique identifier for parallel builds
288
```
289

290
### Authentication
291

292
```bash { .api }
293
PERCY_TOKEN                        # Percy project token
294

295
# Build review authentication (BrowserStack credentials)
296
BROWSERSTACK_USERNAME              # BrowserStack username for build review operations
297
BROWSERSTACK_ACCESS_KEY            # BrowserStack access key for build review operations
298
```
299

300
## Build States and Transitions
301

302
### Build Lifecycle
303

304
1. **Created**: Build is created but no snapshots yet
305
2. **Processing**: Snapshots are being captured and uploaded
306
3. **Pending**: All snapshots uploaded, waiting for processing
307
4. **Finished**: Processing complete, ready for review
308
5. **Approved**: All visual differences approved
309
6. **Rejected**: Build marked as rejected
310

311
### Parallel Build States
312

313
1. **Parallel Started**: Multiple parallel processes begin
314
2. **Shards Processing**: Each parallel process uploads snapshots
315
3. **Finalization**: `percy build finalize` triggers final processing
316
4. **Completed**: All parallel shards processed together
317

318
## Error Handling
319

320
### Common Error Scenarios
321

322
```bash
323
# Handle build wait timeout
324
percy build wait --timeout 600000 || {
325
  echo "Build timed out after 10 minutes"
326
  exit 1
327
}
328

329
# Handle authentication errors
330
percy build approve build_12345 --username user --access-key key || {
331
  echo "Failed to approve build - check credentials"
332
  exit 1
333
}
334

335
# Handle missing build
336
percy build wait --build nonexistent_build || {
337
  echo "Build not found"
338
  exit 1
339
}
340
```
341

342
### Exit Code Handling
343

344
```bash
345
# Check for visual differences
346
percy build wait --fail-on-changes
347
case $? in
348
  0) echo "Build passed - no visual differences" ;;
349
  1) echo "Build error - check logs" ;;
350
  2) echo "Build has visual differences" ;;
351
esac
352
```
353

354
## Authentication
355

356
Build review commands require BrowserStack credentials beyond the regular PERCY_TOKEN:
357

358
### Credentials Setup
359

360
```bash
361
# Set BrowserStack credentials as environment variables
362
export BROWSERSTACK_USERNAME="your-browserstack-username"
363
export BROWSERSTACK_ACCESS_KEY="your-browserstack-access-key"
364

365
# Use in commands (credentials can also be passed via flags)
366
percy build approve build_12345 \
367
  --username "$BROWSERSTACK_USERNAME" \
368
  --access-key "$BROWSERSTACK_ACCESS_KEY"
369
```
370

371
### Permissions Required
372

373
- **Approve/Unapprove**: Requires reviewer or admin permissions
374
- **Reject**: Requires reviewer or admin permissions  
375
- **Delete**: Requires admin permissions
376

377
Review credentials are separate from project tokens and must be obtained from Percy dashboard settings.