chore(docs): Add deployment API docs

[isshaddad]

Adds documentation for deployment management APIs (promote, retrieve, get-latest)

---

[changeset-bot]

⚠️ No Changeset found

Latest commit: a2c0f3b

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[coderabbitai]

Walkthrough

The PR adds API documentation for a Deployments API with three new endpoints. It introduces a new documentation group in the navigation structure pointing to three new MDX documentation files. The OpenAPI specification is extended with three new endpoints under the /api/v1/deployments path: one to retrieve a specific deployment by ID, one to retrieve the latest deployment, and one to promote a deployment version. Each endpoint includes responses, security configurations, and code samples in TypeScript and curl.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	The description is minimal and lacks most required template sections including checklist, testing details, and changelog information.	Complete the PR description by filling in the checklist items, testing steps, and changelog section as specified in the repository's template.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely summarizes the main change: adding documentation for deployment API endpoints.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

🧹 Recent nitpick comments

docs/v3-openapi.yaml (2)

717-734: Consider removing unnecessary Content-Type header from code samples.

The POST /api/v1/deployments/{version}/promote endpoint has no request body, so the Content-Type: application/json header is unnecessary in the code samples.

✨ Suggested cleanup

        - lang: typescript
          source: |-
            const response = await fetch(
              `https://api.trigger.dev/api/v1/deployments/${version}/promote`,
              {
                method: "POST",
                headers: {
                  "Authorization": `Bearer ${secretKey}`,
-                 "Content-Type": "application/json",
                },
              }
            );
            const result = await response.json();
        - lang: curl
          source: |-
            curl -X POST "https://api.trigger.dev/api/v1/deployments/20250228.1/promote" \
-             -H "Authorization: Bearer tr_dev_1234" \
-             -H "Content-Type: application/json"
+             -H "Authorization: Bearer tr_dev_1234"

---

569-581: Consider adding maxItems to the tasks array schema.

The tasks array in the worker object lacks a maxItems constraint. While not strictly required, adding it improves API documentation completeness and helps consumers understand expected limits.

✨ Suggested addition

                      tasks:
                        type: array
+                       maxItems: 1000
                        items:
                          type: object

📜 Recent review details

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 34203d6 and a2c0f3b.

📒 Files selected for processing (5)

• docs/docs.json
• docs/management/deployments/get-latest.mdx
• docs/management/deployments/promote.mdx
• docs/management/deployments/retrieve.mdx
• docs/v3-openapi.yaml

🧰 Additional context used

📓 Path-based instructions (1)

**/*.{js,ts,jsx,tsx,json,md,yaml,yml}

📄 CodeRabbit inference engine (AGENTS.md)

Format code using Prettier before committing

Files:

• docs/docs.json
• docs/v3-openapi.yaml

🪛 Checkov (3.2.334)

docs/v3-openapi.yaml

[medium] 569-582: Ensure that arrays have a maximum number of items

(CKV_OPENAPI_21)

🪛 Gitleaks (8.30.0)

docs/v3-openapi.yaml

[high] 602-605: Discovered a potential authorization token provided in a curl command header, which could compromise the curl accessed resource.

(curl-auth-header)

---

[high] 665-668: Discovered a potential authorization token provided in a curl command header, which could compromise the curl accessed resource.

(curl-auth-header)

---

[high] 730-733: Discovered a potential authorization token provided in a curl command header, which could compromise the curl accessed resource.

(curl-auth-header)

🔇 Additional comments (6)

docs/management/deployments/retrieve.mdx (1)

1-4: LGTM!

The frontmatter correctly references the OpenAPI endpoint defined in v3-openapi.yaml.

docs/management/deployments/promote.mdx (1)

1-4: LGTM!

The frontmatter correctly references the OpenAPI endpoint for promoting deployments.

docs/management/deployments/get-latest.mdx (1)

1-4: LGTM!

The frontmatter correctly references the OpenAPI endpoint for retrieving the latest deployment.

docs/docs.json (1)

272-280: LGTM!

The new Deployments API group is correctly structured and placed consistently with other API groups in the navigation.

docs/v3-openapi.yaml (2)

607-644: Verify schema consistency between deployment endpoints.

The /api/v1/deployments/latest endpoint returns fewer properties than /api/v1/deployments/{deploymentId}. Specifically, it's missing:

• imagePlatform
• externalBuildData
• worker

If both endpoints return the same deployment object from the API, consider aligning the schemas for consistency. If the difference is intentional (e.g., a lighter response for the latest endpoint), consider documenting this distinction in the description.

---

602-605: Static analysis false positive - placeholder token in documentation.

The Gitleaks warning about "authorization token provided in a curl command header" is a false positive. The value tr_dev_1234 is clearly a placeholder token for documentation examples, not an actual secret.

_{✏️ Tip: You can disable this entire section by setting review_details to false in your review settings.}

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[devin-ai-integration]

Devin Review found 2 potential issues.

View issues and 3 additional flags in Devin Review.

[vibe-kanban-cloud]

Review Complete

Your review story is ready!

View Story

Comment !reviewfast on this PR to re-generate the story.