feat: reorgnize commands into github/gitlab specific commands

.github/workflows/docs.yml

@@ -31,5 +31,8 @@ jobs:
       - name: setup
         run: task setup
 
+      - name: generate
+        run: task docs:generate
+
       - name: deploy
         run: task docs:deploy

.github/workflows/test.yml

@@ -46,13 +46,21 @@ jobs:
       - name: Ensure scm-engine binary work
         run: ./scm-engine -h
 
-      - name: Test scm-engine against a GitLab project
+      - name: Test scm-engine against a GitLab project (deprecated)
         run: ./scm-engine evaluate all
         env:
           SCM_ENGINE_TOKEN: "${{ secrets.GITLAB_INTEGRATION_TEST_API_TOKEN }}"
           SCM_ENGINE_CONFIG_FILE: ".scm-engine.gitlab.example.yml"
           GITLAB_PROJECT: "jippi/scm-engine-schema-test"
           GITLAB_BASEURL: https://gitlab.com/
 
+      - name: Test scm-engine against a GitLab project (new)
+        run: ./scm-engine gitlab evaluate all
+        env:
+          SCM_ENGINE_TOKEN: "${{ secrets.GITLAB_INTEGRATION_TEST_API_TOKEN }}"
+          SCM_ENGINE_CONFIG_FILE: ".scm-engine.gitlab.example.yml"
+          GITLAB_PROJECT: "jippi/scm-engine-schema-test"
+          GITLAB_BASEURL: https://gitlab.com/
+
       - name: Show any diff that may be in the project
         run: git diff

.gitignore

@@ -18,3 +18,5 @@
 /scm-engine.exe
 /docs/gitlab/script-attributes.md
 /docs/github/script-attributes.md
+/docs/github/_partials/cmd-*
+/docs/gitlab/_partials/cmd-*

Taskfile.yml

@@ -30,6 +30,19 @@ tasks:
     generates:
       - ./scm-engine
 
+  docs:generate:
+    desc: "Generate docs"
+    cmds:
+      - mkdir -p docs/github/_partials
+      - go run . -h > docs/github/_partials/cmd-root.md
+      - go run . github -h > docs/github/_partials/cmd-github.md
+      - go run . github evaluate -h > docs/github/_partials/cmd-github-evaluate.md
+
+      - mkdir -p docs/gitlab/_partials
+      - go run . -h > docs/gitlab/_partials/cmd-root.md
+      - go run . gitlab -h > docs/gitlab/_partials/cmd-gitlab.md
+      - go run . gitlab evaluate -h > docs/gitlab/_partials/cmd-gitlab-evaluate.md
+      - go run . gitlab server -h > docs/gitlab/_partials/cmd-gitlab-server.md
   docs:server:
     desc: Run Docs dev server with live preview
     cmds:

cmd/conventions.go

@@ -6,7 +6,6 @@ const (
 	FlagConfigFile     = "config"
 	FlagDryRun         = "dry-run"
 	FlagMergeRequestID = "id"
-	FlagProvider       = "provider"
 	FlagSCMBaseURL     = "base-url"
 	FlagSCMProject     = "project"
 	FlagServerListen   = "listen"

cmd/github.go

@@ -0,0 +1,66 @@
+package cmd
+
+import (
+	"github.com/jippi/scm-engine/pkg/state"
+	"github.com/urfave/cli/v2"
+)
+
+var GitHub = &cli.Command{
+	Name:  "github",
+	Usage: "GitHub related commands",
+	Before: func(ctx *cli.Context) error {
+		ctx.Context = state.WithProvider(ctx.Context, "github")
+
+		return nil
+	},
+	Flags: []cli.Flag{
+		&cli.StringFlag{
+			Name:  FlagAPIToken,
+			Usage: "GitHub API token",
+			EnvVars: []string{
+				"SCM_ENGINE_TOKEN", // SCM Engine Native
+			},
+		},
+		&cli.StringFlag{
+			Name:  FlagSCMBaseURL,
+			Usage: "Base URL for the SCM instance",
+			Value: "https://api.github.com/",
+			EnvVars: []string{
+				"SCM_ENGINE_BASE_URL", // SCM Engine Native
+			},
+		},
+	},
+	Subcommands: []*cli.Command{
+		{
+			Name:      "evaluate",
+			Usage:     "Evaluate a Pull Request",
+			Args:      true,
+			ArgsUsage: " [pr_id, pr_id, ...]",
+			Action:    Evaluate,
+			Flags: []cli.Flag{
+				&cli.StringFlag{
+					Name:     FlagSCMProject,
+					Usage:    "GitHub project (example: 'jippi/scm-engine')",
+					Required: true,
+					EnvVars: []string{
+						"GITHUB_REPOSITORY", // GitHub Actions CI
+					},
+				},
+				&cli.StringFlag{
+					Name:  FlagMergeRequestID,
+					Usage: "The Pull Request ID to process, if not provided as a CLI flag",
+					EnvVars: []string{
+						"SCM_ENGINE_PULL_REQUEST_ID", // SCM Engine native
+					},
+				},
+				&cli.StringFlag{
+					Name:  FlagCommitSHA,
+					Usage: "The git commit sha",
+					EnvVars: []string{
+						"GITHUB_SHA", // GitHub Actions
+					},
+				},
+			},
+		},
+	},
+}

cmd/gitlab.go

@@ -0,0 +1,108 @@
+package cmd
+
+import (
+	"github.com/jippi/scm-engine/pkg/state"
+	"github.com/urfave/cli/v2"
+)
+
+var GitLab = &cli.Command{
+	Name:  "gitlab",
+	Usage: "GitLab related commands",
+	Before: func(cCtx *cli.Context) error {
+		cCtx.Context = state.WithBaseURL(cCtx.Context, cCtx.String(FlagSCMBaseURL))
+		cCtx.Context = state.WithProvider(cCtx.Context, "gitlab")
+		cCtx.Context = state.WithToken(cCtx.Context, cCtx.String(FlagAPIToken))
+
+		return nil
+	},
+	Flags: []cli.Flag{
+		&cli.StringFlag{
+			Name:  FlagAPIToken,
+			Usage: "GitLab API token",
+			EnvVars: []string{
+				"SCM_ENGINE_TOKEN", // SCM Engine Native
+			},
+		},
+		&cli.StringFlag{
+			Name:  FlagSCMBaseURL,
+			Usage: "Base URL for the SCM instance",
+			Value: "https://gitlab.com/",
+			EnvVars: []string{
+				"SCM_ENGINE_BASE_URL", // SCM Engine Native
+				"CI_SERVER_URL",       // GitLab CI
+			},
+		},
+	},
+	Subcommands: []*cli.Command{
+		{
+			Name:      "evaluate",
+			Usage:     "Evaluate a Merge Request",
+			Args:      true,
+			ArgsUsage: " [mr_id, mr_id, ...]",
+			Action:    Evaluate,
+			Flags: []cli.Flag{
+				&cli.BoolFlag{
+					Name:  FlagUpdatePipeline,
+					Usage: "Update the CI pipeline status with progress",
+					Value: false,
+					EnvVars: []string{
+						"SCM_ENGINE_UPDATE_PIPELINE",
+					},
+				},
+				&cli.StringFlag{
+					Name:  FlagSCMProject,
+					Usage: "GitLab project (example: 'gitlab-org/gitlab')",
+					EnvVars: []string{
+						"GITLAB_PROJECT",
+						"CI_PROJECT_PATH", // GitLab CI
+					},
+				},
+				&cli.StringFlag{
+					Name:  FlagMergeRequestID,
+					Usage: "The Merge Request ID to process, if not provided as a CLI flag",
+					EnvVars: []string{
+						"CI_MERGE_REQUEST_IID", // GitLab CI
+					},
+				},
+				&cli.StringFlag{
+					Name:  FlagCommitSHA,
+					Usage: "The git commit sha",
+					EnvVars: []string{
+						"CI_COMMIT_SHA", // GitLab CI
+					},
+				},
+			},
+		},
+		{
+			Name:   "server",
+			Usage:  "Start HTTP server for webhook event driven usage",
+			Hidden: true, // DEPRECATED
+			Action: Server,
+			Flags: []cli.Flag{
+				&cli.StringFlag{
+					Name:  FlagWebhookSecret,
+					Usage: "Used to validate received payloads. Sent with the request in the X-Gitlab-Token HTTP header",
+					EnvVars: []string{
+						"SCM_ENGINE_WEBHOOK_SECRET",
+					},
+				},
+				&cli.StringFlag{
+					Name:  FlagServerListen,
+					Usage: "IP + Port that the HTTP server should listen on",
+					Value: "0.0.0.0:3000",
+					EnvVars: []string{
+						"SCM_ENGINE_LISTEN",
+					},
+				},
+				&cli.BoolFlag{
+					Name:  FlagUpdatePipeline,
+					Usage: "Update the CI pipeline status with progress",
+					Value: true,
+					EnvVars: []string{
+						"SCM_ENGINE_UPDATE_PIPELINE",
+					},
+				},
+			},
+		},
+	},
+}

cmd/cmd_evaluate.go → cmd/gitlab_evaluate.go

@@ -11,11 +11,7 @@ import (
 
 func Evaluate(cCtx *cli.Context) error {
 	ctx := state.WithProjectID(cCtx.Context, cCtx.String(FlagSCMProject))
-	ctx = state.WithBaseURL(ctx, cCtx.String(FlagSCMBaseURL))
 	ctx = state.WithCommitSHA(ctx, cCtx.String(FlagCommitSHA))
-	ctx = state.WithDryRun(ctx, cCtx.Bool(FlagDryRun))
-	ctx = state.WithProvider(ctx, cCtx.String(FlagProvider))
-	ctx = state.WithToken(ctx, cCtx.String(FlagAPIToken))
 	ctx = state.WithToken(ctx, cCtx.String(FlagAPIToken))
 	ctx = state.WithUpdatePipeline(ctx, cCtx.Bool(FlagUpdatePipeline))
 

cmd/cmd_server.go → cmd/gitlab_server.go

@@ -56,11 +56,7 @@ func errHandler(ctx context.Context, w http.ResponseWriter, code int, err error)
 
 func Server(cCtx *cli.Context) error {
 	// Initialize context
-	ctx := state.WithDryRun(cCtx.Context, cCtx.Bool(FlagDryRun))
-	ctx = state.WithBaseURL(ctx, cCtx.String(FlagSCMBaseURL))
-	ctx = state.WithToken(ctx, cCtx.String(FlagAPIToken))
-	ctx = state.WithProvider(ctx, cCtx.String(FlagProvider))
-	ctx = state.WithUpdatePipeline(ctx, cCtx.Bool(FlagUpdatePipeline))
+	ctx := state.WithUpdatePipeline(cCtx.Context, cCtx.Bool(FlagUpdatePipeline))
 
 	slogctx.Info(ctx, "Starting HTTP server", slog.String("listen", cCtx.String(FlagServerListen)))
 

docs/github/commands.md

@@ -0,0 +1,19 @@
+# Commands
+
+## `scm-engine`
+
+```plain
+--8<-- "docs/github/_partials/cmd-root.md"
+```
+
+## `scm-engine github`
+
+```plain
+--8<-- "docs/github/_partials/cmd-github.md"
+```
+
+## `scm-engine github evaluate`
+
+```plain
+--8<-- "docs/github/_partials/cmd-github-evaluate.md"
+```

docs/gitlab/commands.md

@@ -0,0 +1,36 @@
+# Commands
+
+## `scm-engine`
+
+```plain
+--8<-- "docs/gitlab/_partials/cmd-root.md"
+```
+
+## `scm-engine gitlab`
+
+```plain
+--8<-- "docs/gitlab/_partials/cmd-gitlab.md"
+```
+
+## `scm-engine gitlab evaluate`
+
+```plain
+--8<-- "docs/gitlab/_partials/cmd-gitlab-evaluate.md"
+```
+
+## `scm-engine gitlab server`
+
+Point your GitLab webhook at the `/gitlab` endpoint.
+
+Support the following events, and they will both trigger an Merge Request `evaluation`
+
+- [`Comments`](https://docs.gitlab.com/ee/user/project/integrations/webhook_events.html#comment-events) - A comment is made or edited on an issue or merge request.
+- [`Merge request events`](https://docs.gitlab.com/ee/user/project/integrations/webhook_events.html#merge-request-events) - A merge request is created, updated, or merged.
+
+!!! tip
+
+    You have access to the raw webhook event payload via `webhook_event.*` fields in Expr script fields when using `server` mode. See the [GitLab Webhook Events documentation](https://docs.gitlab.com/ee/user/project/integrations/webhook_events.html) for available fields.
+
+```plain
+--8<-- "docs/gitlab/_partials/cmd-gitlab-server.md"
+```