0
# Deployment
1

2
Build and deployment functionality for deploying projects to Netlify with support for various contexts, build configurations, and deployment options.
3

4
## Capabilities
5

6
### Deploy Command
7

8
Deploys your project to Netlify with comprehensive options for different deployment scenarios.
9

10
```typescript { .api }
11
/**
12
 * Deploy project to Netlify
13
 * Command: netlify deploy [options]
14
 */
15
interface DeployOptions {
16
  /** Folder to deploy (publish directory) */
17
  dir?: string;
18
  /** Functions folder to deploy */
19
  functions?: string;
20
  /** Deploy to production */
21
  prod?: boolean;
22
  /** Deploy to production if unlocked, draft otherwise */
23
  prodIfUnlocked?: boolean;
24
  /** Alias for deployment (max 37 characters) */
25
  alias?: string;
26
  /** Deprecated, renamed to --alias */
27
  branch?: string;
28
  /** Open project after deploy */
29
  open?: boolean;
30
  /** Deploy log message */
31
  message?: string;
32
  /** Project name or ID */
33
  site?: string;
34
  /** Output deployment information as JSON */
35
  json?: boolean;
36
  /** Deployment timeout in seconds */
37
  timeout?: number;
38
  /** Trigger build without uploading files */
39
  trigger?: boolean;
40
  /** Run build command (default behavior) */
41
  build?: boolean;
42
  /** Skip build command */
43
  noBuild?: boolean;
44
  /** Deploy context for build environment */
45
  context?: string;
46
  /** Force rebundle functions, skip functions cache */
47
  skipFunctionsCache?: boolean;
48
  /** Create new site and deploy (optionally with name) */
49
  createSite?: string | boolean;
50
  /** Team slug for site creation */
51
  team?: string;
52
  /** Upload source zip for edge functions */
53
  uploadSourceZip?: boolean;
54
}
55
```
56

57
**Usage Examples:**
58

59
```bash
60
# Deploy to draft
61
netlify deploy
62

63
# Deploy to production
64
netlify deploy --prod
65

66
# Deploy with custom directory
67
netlify deploy --dir dist --prod
68

69
# Deploy with custom functions directory
70
netlify deploy --dir build --functions lambda --prod
71

72
# Deploy with alias for A/B testing
73
netlify deploy --alias feature-x
74

75
# Deploy with message
76
netlify deploy --prod --message "Release v2.1.0"
77

78
# Deploy and open in browser
79
netlify deploy --prod --open
80

81
# Deploy without running build
82
netlify deploy --no-build --prod
83

84
# Create new site during deployment
85
netlify deploy --create-site "My New Project"
86

87
# Deploy to specific team
88
netlify deploy --create-site --team my-team-slug
89

90
# Deploy with timeout
91
netlify deploy --prod --timeout 600
92

93
# Trigger build without file upload
94
netlify deploy --trigger --prod
95

96
# Get deployment info as JSON
97
netlify deploy --json
98
```
99

100
### Build and Deploy Integration
101

102
The deploy command can integrate with Netlify Build for processing:
103

104
```typescript { .api }
105
/**
106
 * Build integration options during deployment
107
 */
108
interface BuildIntegration {
109
  /** Run Netlify Build during deployment */
110
  runBuild: boolean;
111
  /** Build context (affects environment variables and plugins) */
112
  context: 'production' | 'deploy-preview' | 'branch-deploy' | string;
113
  /** Skip functions caching for fresh builds */
114
  skipFunctionsCache: boolean;
115
  /** Build command override */
116
  buildCommand?: string;
117
  /** Publish directory override */
118
  publishDir?: string;
119
  /** Functions directory override */
120
  functionsDir?: string;
121
}
122
```
123

124
### Deployment Contexts
125

126
Different deployment contexts provide different environments and behaviors:
127

128
```typescript { .api }
129
/**
130
 * Deployment context configuration
131
 */
132
interface DeploymentContext {
133
  /** Context name */
134
  context: 'production' | 'deploy-preview' | 'branch-deploy' | 'dev' | `branch:${string}`;
135
  /** Whether this is a production deployment */
136
  isProduction: boolean;
137
  /** Branch being deployed */
138
  branch: string;
139
  /** Commit SHA being deployed */
140
  commitSha: string;
141
  /** Environment variables for this context */
142
  environmentVariables: Record<string, string>;
143
  /** Whether this deployment is locked for editing */
144
  isLocked: boolean;
145
}
146

147
/**
148
 * Production deployment context
149
 */
150
interface ProductionContext extends DeploymentContext {
151
  context: 'production';
152
  isProduction: true;
153
  /** Production URL */
154
  url: string;
155
  /** SSL certificate status */
156
  sslEnabled: boolean;
157
}
158

159
/**
160
 * Deploy preview context (for pull requests)
161
 */
162
interface DeployPreviewContext extends DeploymentContext {
163
  context: 'deploy-preview';
164
  /** Pull request number */
165
  pullRequestNumber: number;
166
  /** Preview URL */
167
  previewUrl: string;
168
  /** Base branch for comparison */
169
  baseBranch: string;
170
}
171

172
/**
173
 * Branch deploy context
174
 */
175
interface BranchDeployContext extends DeploymentContext {
176
  context: 'branch-deploy';
177
  /** Branch-specific URL */
178
  branchUrl: string;
179
  /** Whether branch deploys are enabled */
180
  branchDeploysEnabled: boolean;
181
}
182
```
183

184
### Deployment Aliases
185

186
Create named deployments for A/B testing and feature previews:
187

188
```typescript { .api }
189
/**
190
 * Deployment alias configuration
191
 */
192
interface DeploymentAlias {
193
  /** Alias name (max 37 characters) */
194
  name: string;
195
  /** Generated alias URL */
196
  url: string;
197
  /** Deployment ID */
198
  deployId: string;
199
  /** Creation timestamp */
200
  createdAt: Date;
201
  /** Expiration timestamp (if temporary) */
202
  expiresAt?: Date;
203
}
204
```
205

206
**Usage Examples:**
207

208
```bash
209
# Create feature branch alias
210
netlify deploy --alias feature-user-auth
211

212
# Create version alias
213
netlify deploy --alias v2-1-0
214

215
# Create testing alias
216
netlify deploy --alias staging-test
217

218
# URLs generated:
219
# https://feature-user-auth--site-name.netlify.app
220
# https://v2-1-0--site-name.netlify.app
221
# https://staging-test--site-name.netlify.app
222
```
223

224
### Site Creation During Deployment
225

226
Create new Netlify sites on-the-fly during deployment:
227

228
```typescript { .api }
229
/**
230
 * Site creation options during deployment
231
 */
232
interface CreateSiteOptions {
233
  /** Site name (max 63 characters, will be part of URL) */
234
  name?: string;
235
  /** Team slug for site ownership */
236
  team?: string;
237
  /** Custom domain to configure */
238
  customDomain?: string;
239
  /** Repository information for CI setup */
240
  repo?: {
241
    provider: 'github' | 'gitlab' | 'bitbucket';
242
    owner: string;
243
    name: string;
244
    branch: string;
245
  };
246
}
247
```
248

249
### Deployment Status and Monitoring
250

251
Track deployment progress and status:
252

253
```typescript { .api }
254
/**
255
 * Deployment status information
256
 */
257
interface DeploymentStatus {
258
  /** Deployment ID */
259
  id: string;
260
  /** Current state */
261
  state: 'new' | 'building' | 'uploading' | 'processing' | 'ready' | 'error';
262
  /** Deployment URL */
263
  url: string;
264
  /** Admin URL for managing deployment */
265
  adminUrl: string;
266
  /** Deployment message */
267
  title: string;
268
  /** Error message if deployment failed */
269
  errorMessage?: string;
270
  /** Build log URL */
271
  buildLogUrl?: string;
272
  /** Functions deployment info */
273
  functions?: Array<{
274
    name: string;
275
    sha: string;
276
    runtime: string;
277
  }>;
278
  /** Upload summary */
279
  summary: {
280
    status: string;
281
    messages: string[];
282
    uploadedFiles: number;
283
    totalFiles: number;
284
  };
285
}
286
```
287

288
### File Upload and Processing
289

290
Handle file uploads and processing during deployment:
291

292
```typescript { .api }
293
/**
294
 * File upload configuration and status
295
 */
296
interface FileUpload {
297
  /** Files to upload */
298
  files: Array<{
299
    path: string;
300
    sha: string;
301
    size: number;
302
  }>;
303
  /** Upload configuration */
304
  config: {
305
    /** Maximum file size in bytes */
306
    maxFileSize: number;
307
    /** Concurrent upload limit */
308
    concurrency: number;
309
    /** Retry configuration */
310
    retry: {
311
      maxAttempts: number;
312
      backoffMultiplier: number;
313
    };
314
  };
315
  /** Upload progress */
316
  progress: {
317
    uploaded: number;
318
    total: number;
319
    percentage: number;
320
    currentFile?: string;
321
  };
322
}
323
```
324

325
### Deployment Output Formats
326

327
Configure deployment output for different use cases:
328

329
```typescript { .api }
330
/**
331
 * Deployment output configuration
332
 */
333
interface DeploymentOutput {
334
  /** Output format */
335
  format: 'human' | 'json';
336
  /** Include deployment logs */
337
  includeLogs: boolean;
338
  /** Include file upload details */
339
  includeFiles: boolean;
340
  /** Include function deployment info */
341
  includeFunctions: boolean;
342
}
343

344
/**
345
 * JSON deployment output structure
346
 */
347
interface JsonDeploymentOutput {
348
  deployId: string;
349
  deployUrl: string;
350
  adminUrl: string;
351
  logsUrl: string;
352
  functionsUrl: string;
353
  state: string;
354
  name: string;
355
  url: string;
356
  branch: string;
357
  commitSha: string;
358
  commitUrl: string;
359
  screenshot?: string;
360
  uploadedFiles?: number;
361
  functionsCount?: number;
362
}
363
```
364

365
### Advanced Deployment Options
366

367
Advanced configurations for complex deployment scenarios:
368

369
```typescript { .api }
370
/**
371
 * Advanced deployment configuration
372
 */
373
interface AdvancedDeployOptions {
374
  /** Skip DNS verification for custom domains */
375
  skipDnsVerification?: boolean;
376
  /** Force deployment even if no changes detected */
377
  force?: boolean;
378
  /** Enable deployment notifications */
379
  notifications?: {
380
    email?: boolean;
381
    slack?: boolean;
382
    webhook?: string;
383
  };
384
  /** Post-deployment hooks */
385
  postDeploy?: {
386
    /** Commands to run after successful deployment */
387
    commands: string[];
388
    /** Environment for post-deploy commands */
389
    environment: Record<string, string>;
390
  };
391
  /** Rollback configuration */
392
  rollback?: {
393
    /** Enable automatic rollback on failure */
394
    autoRollback: boolean;
395
    /** Previous deployment ID to rollback to */
396
    targetDeployment?: string;
397
  };
398
}
399
```