atlantis/docs/queue-api.md

Plan Queue API Documentation

This document describes the API endpoints for managing Atlantis plan queues. The queue system allows users to queue up plan requests when a project/workspace is already locked, providing better resource management and user experience.

Base URL

All API endpoints are relative to your Atlantis server URL. For example, if Atlantis is running at https://atlantis.example.com, the API base URL would be https://atlantis.example.com/api/queues.

Authentication

Currently, the queue API endpoints do not require authentication. However, this may change in future versions. It's recommended to secure your Atlantis instance appropriately.

Endpoints

1. Get All Queues

Retrieves all active plan queues across all projects and workspaces.

Endpoint: GET /api/queues

Response:

{
   "queues": [
      {
         "project": "owner/repo:path",
         "workspace": "default",
         "repo_full_name": "owner/repo",
         "entries": [
            {
               "id": "queue-entry-id",
               "pull_num": 123,
               "username": "user1",
               "time": "2024-01-15 10:30:00",
               "position": 1
            }
         ],
         "updated_at": "2024-01-15 10:30:00"
      }
   ],
   "count": 1
}

Status Codes:

• 200 OK - Successfully retrieved queues
• 500 Internal Server Error - Server error

2. Get Queue Status

Retrieves the current status of a specific queue for a project/workspace combination.

Endpoint: GET /api/queues/{repo}/{project}/{workspace}

Parameters:

• repo (string, required) - Repository full name (e.g., "owner/repo")
• project (string, required) - Project path (e.g., "terraform/prod")
• workspace (string, required) - Workspace name (e.g., "default")

Example: GET /api/queues/owner/repo/terraform/prod/default

Response:

{
   "project": "owner/repo:terraform/prod",
   "workspace": "default",
   "entries": [
      {
         "id": "queue-entry-id",
         "pull_num": 123,
         "username": "user1",
         "time": "2024-01-15 10:30:00",
         "position": 1
      }
   ],
   "updated_at": "2024-01-15 10:30:00"
}

Status Codes:

• 200 OK - Successfully retrieved queue status
• 404 Not Found - Queue not found
• 500 Internal Server Error - Server error

3. Remove from Queue

Removes a specific pull request from a queue.

Endpoint: DELETE /api/queues/{repo}/{project}/{workspace}/{pull_num}

Parameters:

• repo (string, required) - Repository full name (e.g., "owner/repo")
• project (string, required) - Project path (e.g., "terraform/prod")
• workspace (string, required) - Workspace name (e.g., "default")
• pull_num (integer, required) - Pull request number

Example: DELETE /api/queues/owner/repo/terraform/prod/default/123

Response:

{
   "message": "Successfully removed from queue"
}

Status Codes:

• 200 OK - Successfully removed from queue
• 400 Bad Request - Invalid pull number
• 500 Internal Server Error - Server error

Data Models

Queue Entry

Represents a single entry in a plan queue.

{
   "id": "string", // Unique identifier for the queue entry
   "pull_num": 123, // Pull request number
   "username": "string", // Username of the person who queued the request
   "time": "string", // ISO 8601 formatted timestamp when entry was added
   "position": 1 // Position in the queue (1-based)
}

Queue

Represents a complete queue for a project/workspace combination.

{
   "project": "string", // Project identifier (repo:path format)
   "workspace": "string", // Workspace name
   "repo_full_name": "string", // Repository full name
   "entries": [], // Array of queue entries
   "updated_at": "string" // ISO 8601 formatted timestamp of last update
}

Error Responses

All endpoints may return error responses in the following format:

{
   "error": "Error message describing what went wrong"
}

Usage Examples

Using curl

# Get all queues
curl -X GET "https://atlantis.example.com/api/queues"

# Get specific queue status
curl -X GET "https://atlantis.example.com/api/queues/owner/repo/terraform/prod/default"

# Remove from queue
curl -X DELETE "https://atlantis.example.com/api/queues/owner/repo/terraform/prod/default/123"

Using JavaScript

// Get all queues
fetch("/api/queues")
   .then((response) => response.json())
   .then((data) => {
      console.log("Queues:", data.queues);
   });

// Remove from queue
fetch("/api/queues/owner/repo/terraform/prod/default/123", {
   method: "DELETE",
})
   .then((response) => response.json())
   .then((data) => {
      console.log("Result:", data.message);
   });

Web Interface

In addition to the API, Atlantis provides a web interface for managing queues:

• Queue Overview: https://atlantis.example.com/queues - View all active queues
• API Documentation: https://atlantis.example.com/api/queues - Access the API directly

Integration Notes

1. Queue Position Updates: When entries are added or removed from a queue, the positions of remaining entries may change.

2. Concurrent Access: The API is designed to handle concurrent requests safely.

3. Queue Cleanup: Queues are automatically cleaned up when pull requests are closed or merged.

4. Rate Limiting: Consider implementing appropriate rate limiting for production use.

Future Enhancements

The following features may be added in future versions:

• Authentication and authorization
• Queue priority management
• Queue entry metadata
• Webhook notifications for queue changes
• Queue analytics and metrics