list_deployments
Retrieve recent Optimizely DXP deployments with filtering options for status, environment, and pagination to manage deployment history efficiently.
Instructions
📋 List recent deployments with filtering and pagination. REAL-TIME: <2s. Returns deployment IDs, status (InProgress, AwaitingVerification, Succeeded, Failed), source/target environments, and timestamps. Set activeOnly=true to show only in-progress/awaiting deployments. Use pagination (limit, offset) for large deployment histories. All parameters optional. Returns deployment history array. Use get_deployment_status() for detailed info on specific deployment.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| offset | No | ||
| activeOnly | No | Filter to only active deployments (InProgress, AwaitingVerification, Resetting, Completing). Useful for autonomous agents detecting deployment conflicts. | |
| status | No | Filter by specific deployment status | |
| environmentSlot | No | Filter by environment slot | |
| format | No | Response format: concise (minimal fields for token efficiency) or detailed (all fields) | detailed |
| projectName | No | ||
| projectId | No | ||
| apiKey | No | ||
| apiSecret | No |
Implementation Reference
- Entry point handler for the list_deployments tool. Validates inputs, handles self-hosted restrictions, calls core listDeployments method, and formats response.static async handleListDeployments(args: ListDeploymentsArgs): Promise<any> { // Check if this is a self-hosted project if (args.isSelfHosted || args.connectionString) { return ResponseBuilder.invalidParams('Deployment listing is not available for self-hosted projects. Self-hosted projects can only download existing backups and blobs.'); } if (!args.apiKey || !args.apiSecret || !args.projectId) { return ResponseBuilder.invalidParams('Missing required parameters'); } try { const result = await this.listDeployments(args); // DXP-66: Check if result is structured response with data and message if (result && typeof result === 'object' && 'data' in result && 'message' in result) { return ResponseBuilder.successWithStructuredData(result.data, result.message); } // Fallback for legacy string responses return ResponseBuilder.success(result); } catch (error: any) { console.error('List deployments error:', error); return ResponseBuilder.internalError('Failed to list deployments', error.message); } }
- TypeScript interface defining input parameters for list_deployments tool.interface ListDeploymentsArgs { apiKey?: string; apiSecret?: string; projectId?: string; projectName?: string; limit?: number; offset?: number; activeOnly?: boolean; status?: string; environmentSlot?: string; format?: 'concise' | 'detailed'; isSelfHosted?: boolean; connectionString?: string; apiUrl?: string; }
- Core implementation: Fetches deployments via DXPRestClient.getDeployments, filters by activeOnly/status/environmentSlot, supports concise/detailed format, handles errors.static async listDeployments(args: ListDeploymentsArgs): Promise<any> { const { apiKey, apiSecret, projectId, limit, activeOnly = false, status, environmentSlot, format = 'detailed' } = args; // DXP-101: Use REST API instead of PowerShell (3-10x faster, no PowerShell dependency) try { // Get deployments directly from REST API const deployments: DeploymentResponse | DeploymentResponse[] = await DXPRestClient.getDeployments( projectId!, apiKey!, apiSecret!, null, // No specific deployment ID - get all { apiUrl: args.apiUrl } // Support custom API URLs for Optimizely internal team ); // Ensure we have an array let deploymentList: DeploymentResponse[] = Array.isArray(deployments) ? deployments : [deployments]; // DXP-103: Filter to active deployments only if requested if (activeOnly) { const activeStatuses = ['InProgress', 'AwaitingVerification', 'Resetting', 'Completing']; deploymentList = deploymentList.filter(dep => dep.Status && activeStatuses.includes(dep.Status) ); } // DXP-76-1: Filter by specific status if (status) { deploymentList = deploymentList.filter(dep => dep.Status === status); } // DXP-76-1: Filter by environment slot if (environmentSlot) { deploymentList = deploymentList.filter(dep => (dep as any).parameters?.environmentSlot === environmentSlot || (dep as any).TargetEnvironment === environmentSlot ); } // DXP-76-1: Format response based on format parameter if (format === 'concise') { // Concise format - return minimal fields for token efficiency const conciseList = deploymentList.map(dep => ({ id: (dep as any).Id || (dep as any).id, status: dep.Status, environment: (dep as any).parameters?.environmentSlot || (dep as any).TargetEnvironment, startTime: (dep as any).StartTime || (dep as any).Created, percentComplete: dep.PercentComplete || 0 })); // Apply limit if specified const limited = limit ? conciseList.slice(0, limit) : conciseList; return { data: { deployments: limited, count: limited.length }, message: ResponseBuilder.addFooter(`Found ${limited.length} deployment(s)`) }; } // Detailed format - use existing formatter if (deploymentList.length > 0) { return DeploymentFormatters.formatDeploymentList(deploymentList as any, projectId!, limit, args.projectName); } return ResponseBuilder.addFooter(activeOnly ? 'No active deployments found' : 'No deployments found'); } catch (error: any) { // Handle REST API errors const errorDetails = { operation: 'List Deployments', projectId, projectName: args.projectName, apiKey }; // Check if this is an access denied error if (error.statusCode === 401 || error.statusCode === 403) { return ErrorHandler.formatError({ type: 'ACCESS_DENIED', message: 'Access denied to deployment API', statusCode: error.statusCode } as any, errorDetails); } // Generic error handling return ErrorHandler.formatError({ type: 'API_ERROR', message: error.message, statusCode: error.statusCode } as any, errorDetails); } }
- lib/tools/deployment/index.ts:13-15 (handler)DeploymentTools wrapper handler that delegates to DeploymentListOperations.handleListDeployments.static async handleListDeployments(args: any): Promise<any> { return DeploymentListOperations.handleListDeployments(args); }
- Tool metadata/availability definition for list_deployments, including hosting restrictions and description.'list_deployments': { hostingTypes: ['dxp-paas'], category: 'Deployments', description: 'List recent deployments', restrictedMessage: 'Deployment history is only available for DXP PaaS hosting.'