coder · kacpersaw · Jul 9, 2025 · Jul 10, 2025 · Jul 10, 2025 · Jul 10, 2025
diff --git a/cli/parameter.go b/cli/parameter.go
@@ -145,9 +145,11 @@ func parseParameterMapFile(parameterFile string) (map[string]string, error) {
 	return parameterMap, nil
 }
 
-// buildFlags contains options relating to troubleshooting provisioner jobs.
+// buildFlags contains options relating to troubleshooting provisioner jobs
+// and setting the reason for the workspace build.
 type buildFlags struct {
 	provisionerLogDebug bool
+	reason              string
 }
 
 func (bf *buildFlags) cliOptions() []serpent.Option {
@@ -160,5 +162,16 @@ This is useful for troubleshooting build issues.`,
 			Value:  serpent.BoolOf(&bf.provisionerLogDebug),
 			Hidden: true,
 		},
+		{
+			Flag:        "reason",
+			Description: `Sets the reason for the workspace build (cli, vscode_connection).`,
+			Value: serpent.EnumOf(
+				&bf.reason,
+				string(codersdk.BuildReasonCLI),
+				string(codersdk.BuildReasonVSCodeConnection),
+			),
+			Default: string(codersdk.BuildReasonCLI),
+			Hidden:  true,
+		},
 	}
 }
diff --git a/cli/ssh.go b/cli/ssh.go
@@ -873,7 +873,9 @@ func getWorkspaceAndAgent(ctx context.Context, inv *serpent.Invocation, client *
 		// It's possible for a workspace build to fail due to the template requiring starting
 		// workspaces with the active version.
 		_, _ = fmt.Fprintf(inv.Stderr, "Workspace was stopped, starting workspace to allow connecting to %q...\n", workspace.Name)
-		_, err = startWorkspace(inv, client, workspace, workspaceParameterFlags{}, buildFlags{}, WorkspaceStart)
+		_, err = startWorkspace(inv, client, workspace, workspaceParameterFlags{}, buildFlags{
+			reason: string(codersdk.BuildReasonSSHConnection),
+		}, WorkspaceStart)
 		if cerr, ok := codersdk.AsError(err); ok {
 			switch cerr.StatusCode() {
 			case http.StatusConflict:

diff --git a/cli/start.go b/cli/start.go
@@ -169,6 +169,9 @@ func buildWorkspaceStartRequest(inv *serpent.Invocation, client *codersdk.Client
 	if buildFlags.provisionerLogDebug {
 		wbr.LogLevel = codersdk.ProvisionerLogLevelDebug
 	}
+	if buildFlags.reason != "" {
+		wbr.Reason = codersdk.CreateWorkspaceBuildReason(buildFlags.reason)
+	}
 
 	return wbr, nil
 }

diff --git a/cli/start_test.go b/cli/start_test.go
@@ -477,3 +477,39 @@ func TestStart_NoWait(t *testing.T) {
 	pty.ExpectMatch("workspace has been started in no-wait mode")
 	_ = testutil.TryReceive(ctx, t, doneChan)
 }
+
+func TestStart_WithReason(t *testing.T) {
+	t.Parallel()
+	ctx := testutil.Context(t, testutil.WaitShort)
+
+	// Prepare user, template, workspace
+	client := coderdtest.New(t, &coderdtest.Options{IncludeProvisionerDaemon: true})
+	owner := coderdtest.CreateFirstUser(t, client)
+	member, _ := coderdtest.CreateAnotherUser(t, client, owner.OrganizationID)
+	version1 := coderdtest.CreateTemplateVersion(t, client, owner.OrganizationID, nil)
+	coderdtest.AwaitTemplateVersionJobCompleted(t, client, version1.ID)
+	template := coderdtest.CreateTemplate(t, client, owner.OrganizationID, version1.ID)
+	workspace := coderdtest.CreateWorkspace(t, member, template.ID)
+	coderdtest.AwaitWorkspaceBuildJobCompleted(t, client, workspace.LatestBuild.ID)
+
+	// Stop the workspace
+	build := coderdtest.CreateWorkspaceBuild(t, member, workspace, database.WorkspaceTransitionStop)
+	coderdtest.AwaitWorkspaceBuildJobCompleted(t, client, build.ID)
+
+	// Start the workspace with reason
+	inv, root := clitest.New(t, "start", workspace.Name, "--reason", "cli")
+	clitest.SetupConfig(t, member, root)
+	doneChan := make(chan struct{})
+	pty := ptytest.New(t).Attach(inv)
+	go func() {
+		defer close(doneChan)
+		err := inv.Run()
+		assert.NoError(t, err)
+	}()
+
+	pty.ExpectMatch("workspace has been started")
+	_ = testutil.TryReceive(ctx, t, doneChan)
+
+	workspace = coderdtest.MustWorkspace(t, member, workspace.ID)
+	require.Equal(t, codersdk.BuildReasonCLI, workspace.LatestBuild.Reason)
+}
diff --git a/coderd/apidoc/docs.go b/coderd/apidoc/docs.go
diff --git a/coderd/apidoc/swagger.json b/coderd/apidoc/swagger.json
diff --git a/coderd/database/dump.sql b/coderd/database/dump.sql
diff --git a/coderd/database/migrations/000349_extend_workspace_build_reason.down.sql b/coderd/database/migrations/000349_extend_workspace_build_reason.down.sql
@@ -0,0 +1 @@
+-- It's not possible to delete enum values.
diff --git a/coderd/database/migrations/000349_extend_workspace_build_reason.up.sql b/coderd/database/migrations/000349_extend_workspace_build_reason.up.sql
@@ -0,0 +1,5 @@
+ALTER TYPE build_reason ADD VALUE IF NOT EXISTS 'dashboard';
+ALTER TYPE build_reason ADD VALUE IF NOT EXISTS 'cli';
+ALTER TYPE build_reason ADD VALUE IF NOT EXISTS 'ssh_connection';
+ALTER TYPE build_reason ADD VALUE IF NOT EXISTS 'vscode_connection';
+ALTER TYPE build_reason ADD VALUE IF NOT EXISTS 'jetbrains_connection';
diff --git a/coderd/database/models.go b/coderd/database/models.go
diff --git a/coderd/workspacebuilds.go b/coderd/workspacebuilds.go
@@ -11,6 +11,7 @@ import (
 	"slices"
 	"sort"
 	"strconv"
+	"strings"
 	"time"
 
 	"github.com/go-chi/chi/v5"
@@ -329,20 +330,33 @@ func (api *API) workspaceBuildByBuildNumber(rw http.ResponseWriter, r *http.Requ
 func (api *API) postWorkspaceBuilds(rw http.ResponseWriter, r *http.Request) {
 	ctx := r.Context()
 	apiKey := httpmw.APIKey(r)
+
 	workspace := httpmw.WorkspaceParam(r)
 	var createBuild codersdk.CreateWorkspaceBuildRequest
 	if !httpapi.Read(ctx, rw, r, &createBuild) {
 		return
 	}
 
-	builder := wsbuilder.New(workspace, database.WorkspaceTransition(createBuild.Transition)).
+	transition := database.WorkspaceTransition(createBuild.Transition)
+	builder := wsbuilder.New(workspace, transition).
 		Initiator(apiKey.UserID).
 		RichParameterValues(createBuild.RichParameterValues).
 		LogLevel(string(createBuild.LogLevel)).
 		DeploymentValues(api.Options.DeploymentValues).
 		Experiments(api.Experiments).
 		TemplateVersionPresetID(createBuild.TemplateVersionPresetID)
 
+	if transition == database.WorkspaceTransitionStart {
+		if createBuild.Reason == "" {
+			userAgent := r.Header.Get("User-Agent")
+			if strings.HasPrefix(userAgent, "Coder Toolbox") || strings.HasPrefix(userAgent, "Coder Gateway") {
+				builder = builder.Reason(database.BuildReasonJetbrainsConnection)
+			}
+		} else {
+			builder = builder.Reason(database.BuildReason(createBuild.Reason))
+		}
+	}
+
 	var (
 		previousWorkspaceBuild database.WorkspaceBuild
 		workspaceBuild         *database.WorkspaceBuild