feat(cli): add cs preview github command for PR preview environments

Refactor the standalone gh-action-deploy binary into two layers:

- pkg/preview/: generic, provider-agnostic preview environment engine
  (find, create, update, delete workspace + run pipeline)
- cli/cmd/preview_github.go: GitHub-specific subcommand that reads
  GitHub Actions env vars and delegates to pkg/preview

New commands:
  cs preview          - parent command for preview environments
  cs preview github   - GitHub Actions integration

The generic engine in pkg/preview/ can be reused by future providers
(e.g. cs preview gitlab).

Signed-off-by: Alex <132889147+alexvcodesphere@users.noreply.github.com>

Author: alexvcodesphere

.mockery.yml

@@ -38,3 +38,7 @@ packages:
     config:
       all: true
     interfaces:
+  github.com/codesphere-cloud/cs-go/pkg/preview:
+    config:
+      all: true
+    interfaces:

cli/cmd/preview.go

@@ -0,0 +1,26 @@
+// Copyright (c) Codesphere Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+package cmd
+
+import (
+	"github.com/spf13/cobra"
+)
+
+type PreviewCmd struct {
+	cmd *cobra.Command
+}
+
+func AddPreviewCmd(rootCmd *cobra.Command, opts GlobalOptions) {
+	preview := PreviewCmd{
+		cmd: &cobra.Command{
+			Use:   "preview",
+			Short: "Manage preview environments",
+			Long:  `Manage preview environments for pull requests and merge requests. Supports creating, updating, and deleting preview workspaces tied to git provider events.`,
+		},
+	}
+	rootCmd.AddCommand(preview.cmd)
+
+	// Add provider-specific subcommands
+	AddPreviewGitHubCmd(preview.cmd, opts)
+}

cli/cmd/preview_github.go

@@ -0,0 +1,199 @@
+// Copyright (c) Codesphere Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+package cmd
+
+import (
+	"encoding/json"
+	"fmt"
+	"os"
+	"strconv"
+	"strings"
+	"time"
+
+	"github.com/codesphere-cloud/cs-go/pkg/io"
+	"github.com/codesphere-cloud/cs-go/pkg/preview"
+	"github.com/spf13/cobra"
+)
+
+type PreviewGitHubCmd struct {
+	cmd  *cobra.Command
+	Opts PreviewGitHubOpts
+}
+
+type PreviewGitHubOpts struct {
+	GlobalOptions
+	PlanId    *int
+	Env       *[]string
+	VpnConfig *string
+	Branch    *string
+	Stages    *string
+	Timeout   *time.Duration
+}
+
+func (c *PreviewGitHubCmd) RunE(_ *cobra.Command, args []string) error {
+	client, err := NewClient(c.Opts.GlobalOptions)
+	if err != nil {
+		return fmt.Errorf("failed to create Codesphere client: %w", err)
+	}
+
+	teamId, err := c.Opts.GetTeamId()
+	if err != nil {
+		return fmt.Errorf("failed to get team ID: %w", err)
+	}
+
+	// Load GitHub context
+	eventName := os.Getenv("GITHUB_EVENT_NAME")
+	prAction, prNumber := loadGitHubEvent()
+	repository := os.Getenv("GITHUB_REPOSITORY")
+	serverUrl := os.Getenv("GITHUB_SERVER_URL")
+
+	// Determine workspace name: <repo>-#<pr>
+	parts := strings.Split(repository, "/")
+	repo := parts[len(parts)-1]
+	wsName := fmt.Sprintf("%s-#%s", repo, prNumber)
+
+	// Resolve branch
+	branch := c.resolveBranch()
+
+	// Resolve repo URL
+	repoUrl := fmt.Sprintf("%s/%s.git", serverUrl, repository)
+
+	// Parse stages
+	var stages []string
+	for _, s := range strings.Fields(*c.Opts.Stages) {
+		if s != "" {
+			stages = append(stages, s)
+		}
+	}
+
+	// Parse env vars
+	envVars := make(map[string]string)
+	for _, e := range *c.Opts.Env {
+		if idx := strings.Index(e, "="); idx > 0 {
+			envVars[e[:idx]] = e[idx+1:]
+		}
+	}
+
+	cfg := preview.Config{
+		TeamId:    teamId,
+		PlanId:    *c.Opts.PlanId,
+		Name:      wsName,
+		EnvVars:   envVars,
+		VpnConfig: *c.Opts.VpnConfig,
+		Branch:    branch,
+		Stages:    stages,
+		RepoUrl:   repoUrl,
+		Timeout:   *c.Opts.Timeout,
+	}
+
+	// Determine if this is a delete operation
+	isDelete := eventName == "pull_request" && prAction == "closed"
+
+	deployer := preview.NewDeployer(client)
+	result, err := deployer.Deploy(cfg, isDelete)
+	if err != nil {
+		return err
+	}
+
+	// Write GitHub-specific outputs
+	if result != nil {
+		setGitHubOutputs(result.WorkspaceId, result.WorkspaceURL)
+	}
+
+	return nil
+}
+
+// resolveBranch determines the branch to deploy with priority:
+// flag > GITHUB_HEAD_REF > GITHUB_REF_NAME > "main"
+func (c *PreviewGitHubCmd) resolveBranch() string {
+	if c.Opts.Branch != nil && *c.Opts.Branch != "" {
+		return *c.Opts.Branch
+	}
+	if headRef := os.Getenv("GITHUB_HEAD_REF"); headRef != "" {
+		return headRef
+	}
+	if refName := os.Getenv("GITHUB_REF_NAME"); refName != "" {
+		return refName
+	}
+	return "main"
+}
+
+// loadGitHubEvent reads the PR action and number from GITHUB_EVENT_PATH.
+func loadGitHubEvent() (action string, number string) {
+	path := os.Getenv("GITHUB_EVENT_PATH")
+	if path == "" {
+		return "", ""
+	}
+	data, err := os.ReadFile(path)
+	if err != nil {
+		return "", ""
+	}
+	var event struct {
+		Action string `json:"action"`
+		Number int    `json:"number"`
+	}
+	if json.Unmarshal(data, &event) == nil {
+		return event.Action, strconv.Itoa(event.Number)
+	}
+	return "", ""
+}
+
+// setGitHubOutputs writes deployment results to GitHub Actions output files.
+func setGitHubOutputs(wsId int, url string) {
+	if f := os.Getenv("GITHUB_OUTPUT"); f != "" {
+		appendToFile(f, fmt.Sprintf("deployment-url=%s\nworkspace-id=%d\n", url, wsId))
+	}
+
+	if f := os.Getenv("GITHUB_STEP_SUMMARY"); f != "" {
+		appendToFile(f, fmt.Sprintf(
+			"### 🚀 Codesphere Deployment\n\n| Property | Value |\n|----------|-------|\n| **URL** | [%s](%s) |\n| **Workspace** | `%d` |\n",
+			url, url, wsId,
+		))
+	}
+}
+
+func appendToFile(path, content string) {
+	f, err := os.OpenFile(path, os.O_APPEND|os.O_WRONLY, 0644)
+	if err != nil {
+		return
+	}
+	defer f.Close() //nolint:errcheck // best-effort append
+	_, _ = f.WriteString(content)
+}
+
+func AddPreviewGitHubCmd(previewCmd *cobra.Command, opts GlobalOptions) {
+	github := PreviewGitHubCmd{
+		cmd: &cobra.Command{
+			Use:   "github",
+			Short: "Manage GitHub PR preview environments",
+			Long: io.Long(`Manage preview environments for GitHub Pull Requests.
+
+				Automatically detects the PR context from GitHub Actions environment
+				variables (GITHUB_EVENT_NAME, GITHUB_HEAD_REF, GITHUB_REPOSITORY, etc.)
+				and creates, updates, or deletes preview workspaces accordingly.
+
+				On PR open/synchronize: creates or updates a preview workspace.
+				On PR close: deletes the preview workspace.
+
+				Designed to be used from GitHub Actions workflows.`),
+			Example: io.FormatExampleCommands("preview github", []io.Example{
+				{Cmd: "", Desc: "Deploy preview using GitHub Actions environment variables"},
+				{Cmd: "--plan-id 20", Desc: "Deploy preview with a specific plan"},
+				{Cmd: "--stages 'prepare test run'", Desc: "Deploy and run specific pipeline stages"},
+				{Cmd: "--branch feature-x", Desc: "Override the branch to deploy"},
+			}),
+		},
+		Opts: PreviewGitHubOpts{GlobalOptions: opts},
+	}
+
+	github.Opts.PlanId = github.cmd.Flags().Int("plan-id", 8, "Plan ID for the preview workspace")
+	github.Opts.Env = github.cmd.Flags().StringArray("env", []string{}, "Environment variables in KEY=VALUE format")
+	github.Opts.VpnConfig = github.cmd.Flags().String("vpn-config", "", "VPN config name to connect the workspace to")
+	github.Opts.Branch = github.cmd.Flags().StringP("branch", "b", "", "Git branch to deploy (auto-detected from GitHub context if not set)")
+	github.Opts.Stages = github.cmd.Flags().String("stages", "prepare run", "Pipeline stages to run (space-separated: prepare test run)")
+	github.Opts.Timeout = github.cmd.Flags().Duration("timeout", 5*time.Minute, "Timeout for workspace creation/readiness")
+
+	previewCmd.AddCommand(github.cmd)
+	github.cmd.RunE = github.RunE
+}

cli/cmd/root.go

@@ -94,6 +94,7 @@ func GetRootCmd() *cobra.Command {
 	AddGoCmd(rootCmd)
 	AddWakeUpCmd(rootCmd, opts)
 	AddCurlCmd(rootCmd, opts)
+	AddPreviewCmd(rootCmd, opts)
 
 	return rootCmd
 }