feat: add CI/CD integration for PR preview workspaces (ISS-53)

Add `devbox ci preview-up` and `devbox ci preview-down` subcommands that
orchestrate workspace lifecycle with GitHub notifications. New `internal/ci`
package wraps GitHub REST API for PR comments (with idempotent bot marker)
and commit status checks.

Ship composite GitHub Action (`action.yml`) and example workflow for
automated PR preview workspace creation/destruction.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: chuongld20

.github/workflows/preview.yml

@@ -0,0 +1,33 @@
+name: PR Preview
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened, closed]
+
+permissions:
+  pull-requests: write
+  statuses: write
+
+jobs:
+  preview-up:
+    if: github.event.action != 'closed'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: junixlabs/devbox-preview@v1
+        with:
+          action: up
+          server: ${{ secrets.DEVBOX_SERVER }}
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+  preview-down:
+    if: github.event.action == 'closed'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: junixlabs/devbox-preview@v1
+        with:
+          action: down
+          server: ${{ secrets.DEVBOX_SERVER }}
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

action.yml

@@ -0,0 +1,67 @@
+name: devbox-preview
+description: Create and destroy preview workspaces for pull requests
+
+inputs:
+  action:
+    description: 'Action to perform: up or down'
+    required: true
+  server:
+    description: 'Target server hostname or pool name'
+    required: true
+  template:
+    description: 'Workspace template to use (optional)'
+    required: false
+    default: ''
+  devbox-version:
+    description: 'devbox version to install'
+    required: false
+    default: 'latest'
+
+runs:
+  using: composite
+  steps:
+    - name: Install devbox
+      shell: bash
+      env:
+        DEVBOX_VERSION: ${{ inputs.devbox-version }}
+      run: |
+        if [ "$DEVBOX_VERSION" = "latest" ]; then
+          DOWNLOAD_URL="https://github.com/junixlabs/devbox/releases/latest/download/devbox-linux-amd64"
+        else
+          DOWNLOAD_URL="https://github.com/junixlabs/devbox/releases/download/${DEVBOX_VERSION}/devbox-linux-amd64"
+        fi
+        curl -fsSL "$DOWNLOAD_URL" -o /usr/local/bin/devbox
+        chmod +x /usr/local/bin/devbox
+        devbox --version
+
+    - name: Preview Up
+      if: inputs.action == 'up'
+      shell: bash
+      env:
+        GITHUB_TOKEN: ${{ github.token }}
+        INPUT_PR: ${{ github.event.pull_request.number }}
+        INPUT_REPO: ${{ github.repository }}
+        INPUT_SHA: ${{ github.event.pull_request.head.sha }}
+        INPUT_SERVER: ${{ inputs.server }}
+        INPUT_TEMPLATE: ${{ inputs.template }}
+      run: |
+        ARGS="--pr $INPUT_PR"
+        ARGS="$ARGS --repo $INPUT_REPO"
+        ARGS="$ARGS --sha $INPUT_SHA"
+        ARGS="$ARGS --server $INPUT_SERVER"
+        if [ -n "$INPUT_TEMPLATE" ]; then
+          ARGS="$ARGS --template $INPUT_TEMPLATE"
+        fi
+        devbox ci preview-up $ARGS
+
+    - name: Preview Down
+      if: inputs.action == 'down'
+      shell: bash
+      env:
+        GITHUB_TOKEN: ${{ github.token }}
+        INPUT_PR: ${{ github.event.pull_request.number }}
+        INPUT_REPO: ${{ github.repository }}
+      run: |
+        devbox ci preview-down \
+          --pr "$INPUT_PR" \
+          --repo "$INPUT_REPO"

cmd/devbox/main.go

@@ -12,6 +12,7 @@ import (
 	"text/tabwriter"
 	"time"
 
+	"github.com/junixlabs/devbox/internal/ci"
 	"github.com/junixlabs/devbox/internal/config"
 	"github.com/junixlabs/devbox/internal/doctor"
 	devboxerr "github.com/junixlabs/devbox/internal/errors"
@@ -72,6 +73,7 @@ func main() {
 	rootCmd.AddCommand(tuiCmd(wm))
 	rootCmd.AddCommand(snapshotCmd())
 	rootCmd.AddCommand(restoreCmd())
+	rootCmd.AddCommand(ciCmd(wm))
 
 	if err := rootCmd.Execute(); err != nil {
 		printError(err)
@@ -1235,3 +1237,217 @@ func formatBytes(b int64) string {
 	}
 	return formatBytesShort(uint64(b))
 }
+
+func ciCmd(wm workspace.Manager) *cobra.Command {
+	cmd := &cobra.Command{
+		Use:   "ci",
+		Short: "CI/CD integration commands",
+		Long:  "Commands for CI/CD platform integration.\nUsed by GitHub Actions to manage PR preview workspaces.",
+	}
+	cmd.AddCommand(ciPreviewUpCmd(wm))
+	cmd.AddCommand(ciPreviewDownCmd(wm))
+	return cmd
+}
+
+func ciPreviewUpCmd(wm workspace.Manager) *cobra.Command {
+	cmd := &cobra.Command{
+		Use:   "preview-up",
+		Short: "Create a preview workspace for a PR",
+		Long:  "Create a preview workspace for a pull request and post the workspace URL as a PR comment.\nSets a commit status check on the PR head SHA.",
+		RunE: func(cmd *cobra.Command, args []string) error {
+			pr, _ := cmd.Flags().GetInt("pr")
+			repo, _ := cmd.Flags().GetString("repo")
+			sha, _ := cmd.Flags().GetString("sha")
+			serverFlag, _ := cmd.Flags().GetString("server")
+			templateFlag, _ := cmd.Flags().GetString("template")
+
+			token := os.Getenv("GITHUB_TOKEN")
+			if token == "" {
+				return fmt.Errorf("devbox ci preview-up: GITHUB_TOKEN environment variable is required")
+			}
+
+			parts := strings.SplitN(repo, "/", 2)
+			if len(parts) != 2 {
+				return fmt.Errorf("devbox ci preview-up: --repo must be in owner/repo format")
+			}
+			owner, repoName := parts[0], parts[1]
+
+			provider := ci.NewGitHubProvider(owner, repoName, token)
+			ctx := cmd.Context()
+
+			// Set pending status.
+			if err := provider.SetCommitStatus(ctx, sha, ci.StatusPending, "", "Creating preview workspace..."); err != nil {
+				fmt.Fprintf(os.Stderr, "Warning: failed to set pending status: %v\n", err)
+			}
+
+			// Build workspace name scoped by repo to avoid collisions.
+			wsName := fmt.Sprintf("pr-%s-%d", repoName, pr)
+			branch := fmt.Sprintf("pr-%d", pr)
+
+			// Load config for defaults.
+			var cfg *config.DevboxConfig
+			if templateFlag != "" {
+				registry, err := tmpl.NewDefaultRegistry()
+				if err != nil {
+					provider.SetCommitStatus(ctx, sha, ci.StatusFailure, "", "Failed to load template")
+					return fmt.Errorf("devbox ci preview-up: %w", err)
+				}
+				t, err := registry.Get(templateFlag)
+				if err != nil {
+					provider.SetCommitStatus(ctx, sha, ci.StatusFailure, "", "Template not found")
+					return fmt.Errorf("devbox ci preview-up: %w", err)
+				}
+				cfg = t.ToDevboxConfig(wsName, "")
+			} else {
+				var err error
+				cfg, err = config.LoadFromDir(".")
+				if err != nil {
+					// No config file — create minimal config.
+					cfg = &config.DevboxConfig{Name: wsName}
+				}
+			}
+
+			if serverFlag != "" {
+				cfg.Server = serverFlag
+			}
+			if cfg.Server == "" {
+				provider.SetCommitStatus(ctx, sha, ci.StatusFailure, "", "No server specified")
+				return fmt.Errorf("devbox ci preview-up: --server is required")
+			}
+
+			// Create workspace.
+			ws, err := wm.Create(workspace.CreateParams{
+				Name:     wsName,
+				User:     "ci",
+				Server:   cfg.Server,
+				Repo:     cfg.Repo,
+				Branch:   branch,
+				Services: cfg.Services,
+				Ports:    cfg.Ports,
+				Env:      cfg.Env,
+			})
+			if err != nil {
+				// If already exists, start it instead.
+				var wsErr *workspace.WorkspaceError
+				if errors.As(err, &wsErr) && strings.Contains(wsErr.Message, "already exists") {
+					if startErr := wm.Start(wsName); startErr != nil {
+						provider.SetCommitStatus(ctx, sha, ci.StatusFailure, "", "Failed to start workspace")
+						return fmt.Errorf("devbox ci preview-up: %w", startErr)
+					}
+					ws, err = wm.Get(wsName)
+					if err != nil {
+						provider.SetCommitStatus(ctx, sha, ci.StatusFailure, "", "Failed to get workspace")
+						return fmt.Errorf("devbox ci preview-up: %w", err)
+					}
+				} else {
+					provider.SetCommitStatus(ctx, sha, ci.StatusFailure, "", "Failed to create workspace")
+					return fmt.Errorf("devbox ci preview-up: %w", err)
+				}
+			}
+
+			// Get workspace URL via Tailscale.
+			sshExec, err := devboxssh.New()
+			if err != nil {
+				provider.SetCommitStatus(ctx, sha, ci.StatusFailure, "", "SSH connection failed")
+				return fmt.Errorf("devbox ci preview-up: %w", err)
+			}
+			defer sshExec.Close()
+
+			tm := tailscale.NewManager(remoteRunner(sshExec, cfg.Server))
+			for name, port := range ws.Ports {
+				if err := tm.Serve(port, ws.Name); err != nil {
+					fmt.Fprintf(os.Stderr, "Warning: failed to expose port %s (%d): %v\n", name, port, err)
+				}
+			}
+
+			wsURL := ""
+			if tsStatus, err := tm.Status(); err == nil && tsStatus != nil {
+				wsURL = tailscale.WorkspaceURL(tsStatus.Hostname, tsStatus.TailnetName)
+			}
+
+			// Post PR comment with workspace URL.
+			if wsURL != "" {
+				if err := provider.CommentWorkspaceURL(ctx, pr, wsURL); err != nil {
+					fmt.Fprintf(os.Stderr, "Warning: failed to post PR comment: %v\n", err)
+				}
+			}
+
+			// Set success status.
+			if err := provider.SetCommitStatus(ctx, sha, ci.StatusSuccess, wsURL, "Preview workspace ready"); err != nil {
+				fmt.Fprintf(os.Stderr, "Warning: failed to set success status: %v\n", err)
+			}
+
+			fmt.Printf("Preview workspace %q ready\n", wsName)
+			if wsURL != "" {
+				fmt.Printf("URL: %s\n", wsURL)
+			}
+
+			return nil
+		},
+	}
+	cmd.Flags().Int("pr", 0, "Pull request number (required)")
+	cmd.Flags().String("repo", "", "Repository in owner/repo format (required)")
+	cmd.Flags().String("sha", "", "Commit SHA for status check (required)")
+	cmd.Flags().String("server", "", "Target server (required)")
+	cmd.Flags().String("template", "", "Workspace template to use")
+	cmd.MarkFlagRequired("pr")
+	cmd.MarkFlagRequired("repo")
+	cmd.MarkFlagRequired("sha")
+	return cmd
+}
+
+func ciPreviewDownCmd(wm workspace.Manager) *cobra.Command {
+	cmd := &cobra.Command{
+		Use:   "preview-down",
+		Short: "Destroy a PR preview workspace",
+		Long:  "Destroy a preview workspace created for a pull request and clean up the PR comment.",
+		RunE: func(cmd *cobra.Command, args []string) error {
+			pr, _ := cmd.Flags().GetInt("pr")
+			repo, _ := cmd.Flags().GetString("repo")
+
+			token := os.Getenv("GITHUB_TOKEN")
+			if token == "" {
+				return fmt.Errorf("devbox ci preview-down: GITHUB_TOKEN environment variable is required")
+			}
+
+			parts := strings.SplitN(repo, "/", 2)
+			if len(parts) != 2 {
+				return fmt.Errorf("devbox ci preview-down: --repo must be in owner/repo format")
+			}
+			owner, repoName := parts[0], parts[1]
+
+			wsName := fmt.Sprintf("pr-%s-%d", repoName, pr)
+			ctx := cmd.Context()
+
+			// Destroy workspace.
+			ws, err := wm.Get(wsName)
+			if err != nil {
+				fmt.Fprintf(os.Stderr, "Warning: workspace %q not found, cleaning up PR comment only\n", wsName)
+			} else {
+				unservePorts(ws)
+				if err := wm.Destroy(wsName); err != nil {
+					return fmt.Errorf("devbox ci preview-down: %w", err)
+				}
+			}
+
+			// Clean up PR comment.
+			provider := ci.NewGitHubProvider(owner, repoName, token)
+			commentID, err := provider.FindBotComment(ctx, pr)
+			if err != nil {
+				fmt.Fprintf(os.Stderr, "Warning: failed to find bot comment: %v\n", err)
+			} else if commentID != 0 {
+				if err := provider.DeleteComment(ctx, commentID); err != nil {
+					fmt.Fprintf(os.Stderr, "Warning: failed to delete bot comment: %v\n", err)
+				}
+			}
+
+			fmt.Printf("Preview workspace %q destroyed\n", wsName)
+			return nil
+		},
+	}
+	cmd.Flags().Int("pr", 0, "Pull request number (required)")
+	cmd.Flags().String("repo", "", "Repository in owner/repo format (required)")
+	cmd.MarkFlagRequired("pr")
+	cmd.MarkFlagRequired("repo")
+	return cmd
+}

internal/ci/ci.go

@@ -0,0 +1,36 @@
+package ci
+
+import "context"
+
+// botCommentMarker is a hidden HTML comment embedded in PR comments
+// to identify and update bot-created comments idempotently.
+const botCommentMarker = "<!-- devbox-preview -->"
+
+// StatusState represents a GitHub commit status state.
+type StatusState string
+
+const (
+	StatusPending StatusState = "pending"
+	StatusSuccess StatusState = "success"
+	StatusFailure StatusState = "failure"
+	StatusError   StatusState = "error"
+)
+
+// CIProvider defines the interface for CI/CD platform integration.
+type CIProvider interface {
+	// CommentWorkspaceURL posts or updates a PR comment with the workspace URL.
+	CommentWorkspaceURL(ctx context.Context, prNumber int, url string) error
+
+	// FindBotComment returns the comment ID of an existing bot comment on a PR.
+	// Returns 0 if no bot comment exists.
+	FindBotComment(ctx context.Context, prNumber int) (int64, error)
+
+	// UpdateComment updates an existing PR comment by ID.
+	UpdateComment(ctx context.Context, commentID int64, body string) error
+
+	// DeleteComment deletes a PR comment by ID.
+	DeleteComment(ctx context.Context, commentID int64) error
+
+	// SetCommitStatus sets a commit status check on a given SHA.
+	SetCommitStatus(ctx context.Context, sha string, state StatusState, targetURL, description string) error
+}