fix(deploy): fail in CI with descriptive message and instructions if no access token set

.changeset/strong-pianos-provide.md

@@ -0,0 +1,6 @@
+---
+"trigger.dev": patch
+"@trigger.dev/core": patch
+---
+
+Fail fast in CI when running deploy with missing `TRIGGER_ACCESS_TOKEN` and add useful error message with link to docs

docs/github-actions.mdx

@@ -1,9 +1,13 @@
 ---
-title: "GitHub Actions"
-description: "You can easily deploy your tasks with GitHub actions."
+title: "CI / GitHub Actions"
+description: "You can easily deploy your tasks with GitHub actions and other CI environments."
 ---
 
-This simple GitHub action file will deploy your Trigger.dev tasks when new code is pushed to the `main` branch and the `trigger` directory has changes in it.
+The instructions below are specific to GitHub Actions, but the same concepts can be used with other CI systems.
+
+## GitHub Actions example
+
+This simple GitHub action workflow will deploy your Trigger.dev tasks when new code is pushed to the `main` branch and the `trigger` directory has changes in it.
 
 <Warning>
   The deploy step will fail if any version mismatches are detected. Please see the [version

docs/snippets/cli-commands-deploy.mdx

@@ -36,7 +36,9 @@ It performs a few steps to deploy:
 3. Deploys the code to the Trigger.dev instance.
 4. Registers the tasks as a new version in the environment (prod by default).
 
-You can also setup [GitHub Actions](/github-actions) to deploy your tasks automatically.
+## Deploying from CI
+
+When deploying from CI/CD environments such as GitHub Actions, GitLab CI, or Jenkins, you need to authenticate non-interactively by setting the `TRIGGER_ACCESS_TOKEN` environment variable. Please see the [CI / GitHub Actions guide](/github-actions) for more information.
 
 ## Arguments
 

packages/cli-v3/src/commands/login.ts

@@ -22,12 +22,13 @@ import { logger } from "../utilities/logger.js";
 import { spinner } from "../utilities/windows.js";
 import { isLinuxServer } from "../utilities/linux.js";
 import { VERSION } from "../version.js";
-import { env } from "std-env";
+import { env, isCI } from "std-env";
 import { CLOUD_API_URL } from "../consts.js";
 import {
   isPersonalAccessToken,
   NotPersonalAccessTokenError,
 } from "../utilities/isPersonalAccessToken.js";
+import { links } from "@trigger.dev/core/v3";
 
 export const LoginCommandOptions = CommonCommandOptions.extend({
   apiUrl: z.string(),
@@ -210,6 +211,24 @@ export async function login(options?: LoginOptions): Promise<LoginResult> {
         }
       }
 
+      if (isCI) {
+        const apiUrl =
+          env.TRIGGER_API_URL ?? authConfig?.apiUrl ?? opts.defaultApiUrl ?? CLOUD_API_URL;
+
+        const isSelfHosted = apiUrl !== CLOUD_API_URL;
+
+        // This is fine, as the api URL will generally be the same as the dashboard URL for self-hosted instances
+        const dashboardUrl = isSelfHosted ? apiUrl : "https://cloud.trigger.dev";
+
+        throw new Error(
+          `Authentication required in CI environment. Please set the TRIGGER_ACCESS_TOKEN environment variable with a Personal Access Token.
+
+- You can generate one here: ${dashboardUrl}/account/tokens
+
+- For more information, see: ${links.docs.gitHubActions.personalAccessToken}`
+        );
+      }
+
       if (opts.embedded) {
         log.step("You must login to continue.");
       }

packages/core/src/v3/links.ts

@@ -20,6 +20,10 @@ export const links = {
         "https://trigger.dev/docs/queue-concurrency#waiting-for-a-subtask-on-the-same-queue",
       deadlock: "https://trigger.dev/docs/queue-concurrency#deadlock",
     },
+    gitHubActions: {
+      personalAccessToken:
+        "https://trigger.dev/docs/github-actions#creating-a-personal-access-token",
+    },
   },
   site: {
     home: "https://trigger.dev",