feat: add http webhook (#5233)

Signed-off-by: Piotr Pawluk <[email protected]>
Co-authored-by: PePe Amengual <[email protected]>

Author: zendesk-piotrpawluk

cmd/server.go

@@ -153,6 +153,7 @@ const (
 	TFELocalExecutionModeFlag        = "tfe-local-execution-mode"
 	TFETokenFlag                     = "tfe-token"
 	WriteGitCredsFlag                = "write-git-creds" // nolint: gosec
+	WebhookHttpHeaders               = "webhook-http-headers"
 	WebBasicAuthFlag                 = "web-basic-auth"
 	WebUsernameFlag                  = "web-username"
 	WebPasswordFlag                  = "web-password"
@@ -460,6 +461,12 @@ var stringFlags = map[string]stringFlag{
 		description:  "Name used to identify Atlantis for pull request statuses.",
 		defaultValue: DefaultVCSStatusName,
 	},
+	WebhookHttpHeaders: {
+		description: "Additional headers added to each HTTP POST payload when using HTTP webhooks provided as a JSON string." +
+			" The map key is the header name and the value is the header value (string) or values (array of string)." +
+			" For example: `{\"Authorization\":\"Bearer some-token\",\"X-Custom-Header\":[\"value1\",\"value2\"]}`.",
+		defaultValue: "",
+	},
 	WebUsernameFlag: {
 		description:  "Username used for Web Basic Authentication on Atlantis HTTP Middleware",
 		defaultValue: DefaultWebUsername,
@@ -1069,6 +1076,10 @@ func (s *ServerCmd) validate(userConfig server.UserConfig) error {
 		return errors.Wrapf(err, "invalid --%s", AllowCommandsFlag)
 	}
 
+	if _, err := userConfig.ToWebhookHttpHeaders(); err != nil {
+		return errors.Wrapf(err, "invalid --%s", WebhookHttpHeaders)
+	}
+
 	return nil
 }
 

cmd/server_test.go

@@ -151,6 +151,7 @@ var testFlags = map[string]interface{}{
 	VarFileAllowlistFlag:             "/path",
 	VCSStatusName:                    "my-status",
 	IgnoreVCSStatusNames:             "",
+	WebhookHttpHeaders:               `{"Authorization":"Bearer some-token","X-Custom-Header":["value1","value2"]}`,
 	WebBasicAuthFlag:                 false,
 	WebPasswordFlag:                  "atlantis",
 	WebUsernameFlag:                  "atlantis",

runatlantis.io/.vitepress/sidebars.ts

@@ -44,7 +44,7 @@ const en = [
           { text: "Checkout Strategy", link: "/docs/checkout-strategy" },
           { text: "Terraform Versions", link: "/docs/terraform-versions" },
           { text: "Terraform Cloud", link: "/docs/terraform-cloud" },
-          { text: "Using Slack Hooks", link: "/docs/using-slack-hooks" },
+          { text: "Sending Notifications via Webhooks", link: "/docs/sending-notifications-via-webhooks" },
           { text: "Stats", link: "/docs/stats" },
           { text: "FAQ", link: "/docs/faq" },
         ]

runatlantis.io/docs/sending-notifications-via-webhooks.md

@@ -0,0 +1,151 @@
+# Sending notifications via webhooks
+
+It is possible to send notifications to external systems whenever an apply is being done.
+
+You can make requests to any HTTP endpoint or send messages directly to your Slack channel.
+
+::: tip NOTE
+Currently only `apply` events are supported.
+:::
+
+## Configuration
+
+Webhooks are configured in Atlantis [server-side configuration](server-configuration.md).
+There can be many webhooks: sending notifications to different destinations or for different
+workspaces/branches. Here is example configuration to send Slack messages for every apply:
+
+```yaml
+webhooks:
+- event: apply
+  kind: slack
+  channel: my-channel-id
+```
+
+If you are deploying Atlantis as a Helm chart, this can be implemented via the `config` parameter available for [chart customizations](https://github.com/runatlantis/helm-charts#customization):
+
+```yaml
+## Use Server Side Config,
+## ref: https://www.runatlantis.io/docs/server-configuration.html
+config: |
+   ---
+   webhooks:
+     - event: apply
+       kind: slack
+       channel: my-channel-id
+```
+
+### Filter on workspace/branch
+
+To limit notifications to particular workspaces or branches, use `workspace-regex` or `branch-regex` parameters.
+If the workspace **and** branch matches respective regex, an event will be sent. Note that empty regular expression
+(a result of unset parameter) matches every string.
+
+## Using HTTP webhooks
+
+You can send POST requests with JSON payload to any HTTP/HTTPS server.
+
+### Configuring Atlantis
+
+In your Atlantis [server-side configuration](server-configuration.md) you can add the following:
+
+```yaml
+webhooks:
+- event: apply
+  kind: http
+  url: https://example.com/hooks
+```
+
+The `apply` event information will be POSTed to `https://example.com/hooks`.
+
+You can supply any additional headers with `--webhook-http-headers` parameter (or environment variable),
+for example for authentication purposes. See [webhook-http-headers](server-configuration.md#webhook-http-headers) for details.
+
+### JSON payload
+
+The payload is a JSON-marshalled [ApplyResult](https://pkg.go.dev/github.com/runatlantis/atlantis/server/events/webhooks#ApplyResult) struct.
+
+Example payload:
+
+```json
+{
+  "Workspace": "default",
+  "Repo": {
+    "FullName": "octocat/Hello-World",
+    "Owner": "octocat",
+    "Name": "Hello-World",
+    "CloneURL": "https://:@github.com/octocat/Hello-World.git",
+    "SanitizedCloneURL": "https://:<redacted>@github.com/octocat/Hello-World.git",
+    "VCSHost": {
+      "Hostname": "github.com",
+      "Type": 0
+    }
+  },
+  "Pull": {
+    "Num": 2137,
+    "HeadCommit": "7fd1a60b01f91b314f59955a4e4d4e80d8edf11d",
+    "URL": "https://github.com/octocat/Hello-World/pull/2137",
+    "HeadBranch": "feature/some-branch",
+    "BaseBranch": "main",
+    "Author": "octocat",
+    "State": 0,
+    "BaseRepo": {
+      "FullName": "octocat/Hello-World",
+      "Owner": "octocat",
+      "Name": "Hello-World",
+      "CloneURL": "https://:@github.com/octocat/Hello-World.git",
+      "SanitizedCloneURL": "https://:<redacted>@github.com/octocat/Hello-World.git",
+      "VCSHost": {
+        "Hostname": "github.com",
+        "Type": 0
+      }
+    }
+  },
+  "User": {
+    "Username": "octocat",
+    "Teams": null
+  },
+  "Success": true,
+  "Directory": "terraform/example", 
+  "ProjectName": "example-project"
+}
+```
+
+## Using Slack hooks
+
+For this you'll need to:
+
+* Create a Bot user in Slack
+* Configure Atlantis to send notifications to Slack.
+
+### Configuring Slack for Atlantis
+
+* Go to [Slack: Apps](https://api.slack.com/apps)
+* Click the `Create New App` button
+* Select `From scratch` in the dialog that opens
+* Give it a name, e.g. `atlantis-bot`.
+* Select your Slack workspace
+* Click `Create App`
+* On the left go to `oAuth & Permissions`
+* Scroll down to Scopes | Bot Token Scopes and add the following OAuth scopes:
+  * `channels:read`
+  * `chat:write`
+  * `groups:read`
+  * `incoming-webhook`
+  * `mpim:read`
+* Install the app onto your Slack workspace
+* Copy the `Bot User OAuth Token` and provide it to Atlantis by using `--slack-token=xoxb-xxxxxxxxxxx` or via the environment `ATLANTIS_SLACK_TOKEN=xoxb-xxxxxxxxxxx`.
+* Create a channel in your Slack workspace (e.g. `my-channel`) or use existing
+* Add the app to Created channel or existing channel ( click channel name then tab integrations, there Click "Add apps"
+
+### Configuring Atlantis
+
+After following the above steps it is time to configure Atlantis. Assuming you have already provided the `slack-token` (via parameter or environment variable) you can now instruct Atlantis to send `apply` events to Slack.
+
+In your Atlantis [server-side configuration](server-configuration.md) you can now add the following:
+
+```yaml
+webhooks:
+- event: apply
+  kind: slack
+  channel: my-channel-id
+```

runatlantis.io/docs/server-configuration.md

@@ -1254,7 +1254,7 @@ This is useful when you have many projects and want to keep the pull request cle
   ATLANTIS_SLACK_TOKEN='token'
   ```
 
-  API token for Slack notifications. See [Using Slack hooks](using-slack-hooks.md).
+  API token for Slack notifications. See [Using Slack hooks](sending-notifications-via-webhooks.md#using-slack-hooks).
 
 ### `--ssl-cert-file`
 
@@ -1425,6 +1425,18 @@ The effect of the race condition is more evident when using parallel configurati
 
   Username used for Basic Authentication on the Atlantis web service. Defaults to `atlantis`.
 
+### `--webhook-http-headers`
+
+  ```bash
+  atlantis server --webhook-http-headers='{"Authorization":"Bearer some-token","X-Custom-Header":["value1","value2"]}'
+  # or
+  ATLANTIS_WEBHOOK_HTTP_HEADERS='{"Authorization":"Bearer some-token","X-Custom-Header":["value1","value2"]}'
+  ```
+
+  Additional headers added to each HTTP POST payload when using [http webhooks](sending-notifications-via-webhooks.md#using-http-webhooks)
+  provided as a JSON string. The map key is the header name and the value is the header value
+  (string) or values (array of string).
+
 ### `--websocket-check-origin`
 
   ```bash

runatlantis.io/docs/using-slack-hooks.md

@@ -660,12 +660,13 @@ func (p *DefaultProjectCommandRunner) doApply(ctx command.ProjectContext) (apply
 	outputs, err := p.runSteps(ctx.Steps, ctx, absPath)
 
 	p.Webhooks.Send(ctx.Log, webhooks.ApplyResult{ // nolint: errcheck
-		Workspace: ctx.Workspace,
-		User:      ctx.User,
-		Repo:      ctx.Pull.BaseRepo,
-		Pull:      ctx.Pull,
-		Success:   err == nil,
-		Directory: ctx.RepoRelDir,
+		Workspace:   ctx.Workspace,
+		User:        ctx.User,
+		Repo:        ctx.Pull.BaseRepo,
+		Pull:        ctx.Pull,
+		Success:     err == nil,
+		Directory:   ctx.RepoRelDir,
+		ProjectName: ctx.ProjectName,
 	})
 
 	if err != nil {

server/events/project_command_runner.go

@@ -0,0 +1,65 @@
+package webhooks
+
+import (
+	"bytes"
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"regexp"
+
+	"github.com/pkg/errors"
+	"github.com/runatlantis/atlantis/server/logging"
+)
+
+// HttpWebhook sends webhooks to any HTTP destination.
+type HttpWebhook struct {
+	Client         *HttpClient
+	WorkspaceRegex *regexp.Regexp
+	BranchRegex    *regexp.Regexp
+	URL            string
+}
+
+// Send sends the webhook to URL if workspace and branch matches their respective regex.
+func (h *HttpWebhook) Send(_ logging.SimpleLogging, applyResult ApplyResult) error {
+	if !h.WorkspaceRegex.MatchString(applyResult.Workspace) || !h.BranchRegex.MatchString(applyResult.Pull.BaseBranch) {
+		return nil
+	}
+	if err := h.doSend(applyResult); err != nil {
+		return errors.Wrap(err, fmt.Sprintf("sending webhook to %q", h.URL))
+	}
+	return nil
+}
+
+func (h *HttpWebhook) doSend(applyResult ApplyResult) error {
+	body, err := json.Marshal(applyResult)
+	if err != nil {
+		return err
+	}
+	req, err := http.NewRequest("POST", h.URL, bytes.NewBuffer(body))
+	if err != nil {
+		return err
+	}
+	req.Header.Set("Content-Type", "application/json")
+	for header, values := range h.Client.Headers {
+		for _, value := range values {
+			req.Header.Add(header, value)
+		}
+	}
+	resp, err := h.Client.Client.Do(req)
+	if err != nil {
+		return err
+	}
+	defer resp.Body.Close()
+	if resp.StatusCode != http.StatusOK {
+		respBody, _ := io.ReadAll(resp.Body)
+		return fmt.Errorf("returned status code %d with response %q", resp.StatusCode, respBody)
+	}
+	return nil
+}
+
+// HttpClient wraps http.Client allowing to add arbitrary Headers to a request.
+type HttpClient struct {
+	Client  *http.Client
+	Headers map[string][]string
+}