Skip to content

Using generic CI/CD tools for your IaC automation? 🤖⚙️

Download the Build vs Buy Guide→

Notification policy»

Purpose»

Info

Please note, we currently don't support importing rego.v1

Notification policies can be used to filter, route and adjust the body of notification messages sent by Spacelift. The policy works at the Space level meaning that it does not need to be attached to a specific stack, but rather is always evaluated if the Space it's in can be accessed by whatever action is being evaluated. It's also important to note that all notifications go through the policy evaluation. This means any of them can be redirected to the routes defined in the policy.

A notification policy can define the following rules:

  • inbox - allows messages to be routed to the Spacelift notification inbox;
  • slack - allows messages to be routed to a given slack channel;
  • webhook - allows messages to be routed to a given webhook;
  • pull_request - allows messages to be routed to one or more pull requests;

If no rules match no action is taken.

Data input»

This is the schema of the data input that each policy request can receive:

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
{
  "account": {
    "name": "string"
  },
  "module_version": {
    "module": {
      "id": "string - unique ID of the module",
      "administrative": "boolean - is the module administrative",
      "branch": "string - tracked branch of the module",
      "labels": ["string - list of arbitrary, user-defined selectors"],
      "namespace": "string - repository namespace, only relevant to GitLab repositories",
      "name": "string - name of the module",
      "project_root": "optional string - project root as set on the Module, if any",
      "repository": "string - name of the source repository",
      "terraform_provider": "string - name of the main Terraform provider used by the module",
      "space": {
        "id": "string - id of a space",
        "labels": ["string - list of arbitrary, user-defined selectors"],
        "name": "string - name of a the space"
      },
      "worker_pool": {
        "public": "boolean - worker pool information",
        "id": "string - unique ID of the worker pool",
        "name": "string - name of the worker pool",
        "labels": ["string - list of arbitrary, user-defined selectors"]
      }
    },
    "version": {
      "commit": {
        "author": "string",
        "branch": "string",
        "created_at": "number (timestamp in nanoseconds)",
        "hash": "string",
        "message": "string",
        "url": "string"
      },
      "created_at": "number - creation Unix timestamp in nanoseconds",
      "id": "string - id of the version being created",
      "latest": "boolean - is the module version latest",
      "number": "string - semver version number",
      "state": "string - current module state: ACTIVE, FAILED",
      "test_runs": [{
        "created_at": "number (timestamp in nanoseconds)",
        "id": "string - id of the test",
        "state": "string - state of the test",
        "title": "string - title of the test",
        "updated_at": "number (timestamp in nanoseconds)",
      }]
    }
  },
  "run_updated": {
    "state": "string",
    "username": "string",
    "note": "string",
    "run":{
      "based_on_local_workspace": "boolean - whether the run stems from a local preview",
      "branch": "string - the branch the run was triggered from",
      "changes": [
        {
          "action": "string enum - added | changed | deleted",
          "entity": {
            "address": "string - full address of the entity",
            "data": "object - detailed information about the entity, shape depends on the vendor and type",
            "name": "string - name of the entity",
            "type": "string - full resource type or \"output\" for outputs",
            "entity_vendor": "string - the name of the vendor",
            "entity_type": "string - the type of entity, possible values depend on the vendor"
          },
          "phase": "string enum - plan | apply"
        }
      ],
      "command": "string",
      "commit": {
        "author": "string",
        "branch": "string",
        "created_at": "number (timestamp in nanoseconds)",
        "hash": "string",
        "message": "string",
        "url": "string"
      },
      "created_at": "number (timestamp in nanoseconds)",
      "creator_session": {
        "admin": "boolean",
        "creator_ip": "string",
        "login": "string",
        "name": "string",
        "teams": ["string"],
        "machine": "boolean - whether the run was kicked off by a human or a machine"
      },
      "drift_detection": "boolean",
      "flags": ["string"],
      "id": "string",
      "runtime_config": {
        "after_apply": ["string"],
        "after_destroy": ["string"],
        "after_init": ["string"],
        "after_perform": ["string"],
        "after_plan": ["string"],
        "after_run": ["string"],
        "before_apply": ["string"],
        "before_destroy": ["string"],
        "before_init": ["string"],
        "before_perform": ["string"],
        "before_plan": ["string"],
        "environment": "map[string]string",
        "project_root": "string",
        "runner_image": "string",
        "terraform_version": "string"
      },
      "policy_receipts": [{
         "flags": ["string - flag assigned to the policy"],
         "name": "string - name of the policy",
         "outcome": "string - outcome of the policy",
         "type": "string - type of the policy"
       }],
      "state": "string",
      "triggered_by": "string or null",
      "type": "string - PROPOSED or TRACKED",
      "updated_at": "number (timestamp in nanoseconds)",
      "user_provided_metadata": ["string"]
    },
    "stack": {
      "administrative": "boolean",
      "autodeploy": "boolean",
      "autoretry": "boolean",
      "branch": "string",
      "id": "string",
      "labels": ["string"],
      "locked_by": "string or null",
      "name": "string",
      "namespace": "string or null",
      "project_root": "string or null",
      "repository": "string",
      "space": {
        "id": "string",
        "labels": ["string"],
        "name": "string"
      },
      "state": "string",
      "terraform_version": "string or null",
      "tracked_commit": {
        "author": "string",
        "branch": "string",
        "created_at": "number (timestamp in nanoseconds)",
        "hash": "string",
        "message": "string",
        "url": "string"
      }
    },
    "timing": [
      {
        "duration": "number (in nanoseconds)",
        "state": "string"
      }
    ],
    "urls": {
      "run": "string - URL to the run"
    }
  },
  "webhook_endpoints": [
    {
      "id": "custom-hook2",
      "labels": [
        "example-label1",
        "example-label2"
      ]
    }
  ],
  "internal_error": {
    "error": "string",
    "message": "string",
    "severity": "string - INFO, WARNING, ERROR"
  }
}

The final JSON object received as input will depend on the type of notification being sent. Event-dependent objects will only be present when those events happen. The best way to see what input your Notification policy received is to enable sampling and check the Policy Workbench, but you can also use the table below as a reference:

Object Received Event
account Any event
webhook_endpoints Any event
run_updated Run Updated
internal_error Internal error occurred
module_version Module version updated

Policy in practice»

Using the notification policy, you can completely re-write notifications or control where and when they are sent. Let's look into how the policy works for each of the defined routes.

Choosing a Space for your policy»

When creating notification policies you should take into account the Space in which you're creating them. Generally the policy follows the same conventions as any other Spacelift component, with a few small caveats.

Determining Space for run update notifications»

Run update messages will rely on the Space that the run is happening in. It will check any policies in that Space including policies inherited from other Spaces.

Determining Space for internal errors»

Most internal errors will check for notification policies inside of the root Space. However if the policy is reporting about a component that belongs to a certain Space and it can determine to which one it is, then it will check for policies in that or any inherited Space. Here is a list of components it will check in order:

  • Stack
  • Worker pool
  • AWS integration
  • Policy

Info

If you are new to spaces, consider further exploring our documentation about them here

Inbox notifications»

Inbox notifications are what you receive in your Spacelift notification inbox. By default, these are errors that happened during some kind of action execution inside Spacelift and are always sent even if you do not have a policy created. However using the policy allows you to alter the body of those errors to add additional context, or even more importantly it allows you to create your own unique notifications.

The inbox rule accepts multiple configurable parameters:

  • title - a custom title for the message (Optional)
  • body - a custom message body (Optional)
  • severity - the severity level for the message (Optional)

Creating new inbox notifications»

For example here is an inbox rule which will send INFO level notification messages to your inbox when a tracked run has finished:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
package spacelift

 inbox[{
  "title": "Tracked run finished!",
  "body": sprintf("http://example.app.spacelift.io/stack/%s/run/%s has finished", [stack.id, run.id]),
  "severity": "INFO",
 }] {
   stack := input.run_updated.stack
   run := input.run_updated.run
   run.type == "TRACKED"
   run.state == "FINISHED"
 }

View the example in the rego playground.

Slack messages»

Slack messages can also be controlled using the notification policy, but before creating any policies that interact with Slack you will need to add the slack integration to your Spacelift account.

Info

The documentation section about Slack includes additional information like: available actions, slack access policies and more. Consider exploring that part of documentation first.

Another important point to mention is that the rules for Slack require a channel_id to be defined. This can be found at the bottom of a channel's About section in Slack:

Now you should be ready to define rules for routing Slack messages. Slack rules allow you to make the same filtering decisions as any other rule in the policy. They also allow you to edit the message bodies themselves in order to create custom messages.

The Slack rules accept multiple configurable parameters:

  • channel_id - the Slack channel to which the message will be delivered (Required)
  • message - a custom message to be sent (Optional)

Filtering and routing messages»

For example if you wanted to receive only finished runs on a specific Slack channel you would define a rule like this:

1
2
3
4
5
6
7
8
package spacelift

slack[{"channel_id": "C0000000000"}] {
  input.run_updated != null

  run := input.run_updated.run
  run.state == "FINISHED"
}

View the example in the rego playground.

Changing the message body»

Together with filtering and routing messages you can also alter the message body itself, here is an example for sending a custom message where a run which tries to attach a policy requires confirmation:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
package spacelift

slack[{
  "channel_id": "C0000000000",
  "message": sprintf("http://example.app.spacelift.io/stack/%s/run/%s is trying to attach a policy!", [stack.id, run.id]),
}] {
  stack := input.run_updated.stack
  run := input.run_updated.run
  run.type == "TRACKED"
  run.state == "UNCONFIRMED"
  change := run.changes[_]
  change.phase == "plan"
  change.entity.type == "spacelift_policy_attachment"
}

View the example in the rego playground.

Webhook requests»

Info

This section of documentation requires you have configured at least one Named Webhook. Consider exploring that part of documentation first.

Webhook notifications are a very powerful part of the notification policy. Using them, one is able to not only receive webhooks on specific events that happen in Spacelift, but also craft unique requests to be consumed by some third-party.

The notification policy relies on named webhooks which can be created and managed in the Webhooks section of Spacelift. Any policy evaluation will always receive a list of possible webhooks together with their labels as input. The data received in the policy input should be used to determine which webhook will be used when sending the request.

The webhook policy accepts multiple configurable parameters:

  • endpoint_id - endpoint id (slug) to which the webhook will be delivered (Required)
  • headers - a key value map which will be appended to request headers (Optional)
  • payload - a custom valid JSON object to be sent as request body (Optional)
  • method - a HTTP method to use when sending the request (Optional)

Filtering webhook requests»

Filtering and selecting webhooks can be done by using the received input data. Rules can be created where only specific actions should trigger a webhook being sent. For example we could define a rule which would allow a webhook to be sent about any drift detection run:

1
2
3
4
5
6
7
8
package spacelift

webhook[{"endpoint_id": endpoint.id}] {
  endpoint := input.webhook_endpoints[_]
  endpoint.id == "drift-hook"
  input.run_updated.run.drift_detection == true
  input.run_updated.run.type == "PROPOSED"
}

View the example in the rego playground.

Creating a custom webhook request»

All requests sent will always include the default headers for verification, a payload which is appropriate for the message type and the method set as POST. However, by using the webhook rule we can modify the body of the request, change the method or add additional headers. For example, if we wanted to define a completely custom request for a tracked run we would define a rule like this:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
package spacelift

webhook[wbdata] {
  endpoint := input.webhook_endpoints[_]
  endpoint.id == "testing-notifications"
  wbdata := {
    "endpoint_id": endpoint.id,
    "payload": {
      "custom_field": "This is a custom message",
      "run_type": input.run_updated.run.type,
      "run_state": input.run_updated.run.state,
      "updated_at": input.run_updated.run.updated_at,
    },
    "method": "PUT",
    "headers": {
      "custom-header": "custom",
    },
  }

  input.run_updated.run.type == "TRACKED"
}

View the example in the rego playground.

Using custom webhook requests also makes it quite easy to integrate Spacelift with any third-party webhook consumer.

Custom webhook requests in action»

Discord integration»

Discord can be integrated to receive updates about Spacelift by simply creating a new webhook endpoint in your Discord server's integrations section and providing that as the endpoint when creating a new named webhook.

Info

For more information about making Discord webhooks follow their official webhook guide.

After creating the webhook on both Discord and Spacelift you will need to define a new webhook rule like this:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
# Send updates about tracked runs to discord.
webhook[wbdata] {
  endpoint := input.webhook_endpoints[_]
  endpoint.id == "YOUR_WEBHOOK_ID_HERE"
  stack := input.run_updated.stack
  run := input.run_updated.run
  wbdata := {
    "endpoint_id": endpoint.id,
    "payload": {
      "embeds": [{
        "title": "Tracked run triggered!",
        "description": sprintf("Stack: [%s](http://example.app.spacelift.io/stack/%s)\nRun ID: [%s](http://example.app.spacelift.io/stack/%s/run/%s)\nRun state: %s", [stack.name,stack.id,run.id,stack.id, run.id,run.state]),
        }]
     }
  }
  input.run_updated.run.type == "TRACKED"
}

And that's it! You should now be receiving updates about tracked runs to your Discord server:

Pull request notifications»

Pull request notifications are a very powerful part of the notification policy. Using them, one is able to not only target a single pull request but also pull requests targeting a specific branch or commit.

The pull request rule accepts multiple configurable parameters:

  • id - a pull request ID (Optional)
  • commit - a target commit SHA (Optional)
  • branch - a target branch (Optional)
  • body - a custom comment body (Optional)
  • deduplication_key - a deduplication key for updating PR comments (Optional)

Creating a pull request comment»

For example here is a rule which will add a comment (containing a default body) to the pull request that triggered the run:

1
2
3
4
5
6
7
8
9
package spacelift

import future.keywords.contains
import future.keywords.if

pull_request contains {"id": run.commit.pull_request_id} if {
 run := input.run_updated.run
 run.state == "FINISHED"
}

Hint

It works best in combination with a push policy to create proposed runs on pull requests.

View the example in the rego playground.

Updating an existing pull request comment»

Info

This feature is currently only available for GitHub and GitHub Enterprise VCS integrations. We intend to add support for the rest of the supported VCS integrations in the near future.

The following example will add a comment to the pull request that triggered the run, and will update that comment for every run state change, instead of creating new comments.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
package spacelift

import future.keywords

pull_request contains {
"id": run.commit.pull_request_id,
"body": sprintf("Run %s is %s", [run.id, run.state]),
"deduplication_key": deduplication_key,
} if {
 run := input.run_updated.run
 deduplication_key := input.run_updated.stack.id
}

The essential aspect for updating existing comments is the deduplication_key, which must have a constant value throughout the PR's lifetime to update the same comment. If the deduplication_key changes but a comment was created with the old deduplication_key, a new comment will be created and updated.

The deduplication_key is associated with the PR using it, so using the same deduplication_key on different PRs is safe and will not cause collisions.

To use this with existing policies, simply add deduplication_key := input.run_updated.stack.id (or another constant value) to the condition of the pull_request rule.

View the example in the rego playground.

Adding a comment to pull requests targeting a specific commit»

You specify a target commit SHA using the commit parameter:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
package spacelift

import future.keywords.contains
import future.keywords.if

pull_request contains {
 "commit": run.commit.hash,
 "body": sprintf("https://%s.app.spacelift.io/stack/%s/run/%s has finished", [input.account.name, stack.id, run.id]),
} if {
 stack := input.run_updated.stack
 run := input.run_updated.run
 run.state == "FINISHED"
}

View the example in the rego playground.

Adding a comment to pull requests targeting a specific branch»

Provide the branch name using the branch parameter:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
package spacelift

import future.keywords.contains
import future.keywords.if

pull_request contains {
 "branch": "main",
 "body": sprintf("https://%s.app.spacelift.io/stack/%s/run/%s has finished", [input.account.name, stack.id, run.id]),
} if {
 stack := input.run_updated.stack
 run := input.run_updated.run
 run.state == "FINISHED"
}

Hint

Please note that branch is the base branch of the pull request. For example, if it's "branch": input.run_updated.stack.branch, that'd mean that the policy would comment into every pull request that targets the tracked branch of the stack.

View the example in the rego playground.

Changing the comment body»

You can customize the comment body, even include logs from various run phases by including a corresponding placeholder:

  • spacelift::logs::initializing placeholder will be replaces with logs from the initializing phase
  • spacelift::logs::preparing placeholder will be replaces with logs from the preparing phase
  • spacelift::logs::planning placeholder will be replaced with logs from the planning phase
  • spacelift::logs::applying placeholder will be replaced with logs from the applying phase
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
package spacelift

import future.keywords.contains
import future.keywords.if

pull_request contains {
 "id": run.commit.pull_request_id,
 "body": body,
} if {
 stack := input.run_updated.stack
 run := input.run_updated.run
 run.state == "FINISHED"

 body := sprintf(
  `https://%s.app.spacelift.io/stack/%s/run/%s has finished

## Planning logs

%s
spacelift::logs::planning
%s
`,
  [input.account.name, stack.id, run.id, "```", "```"],
 )
}

View the example in the rego playground.

Complex example: adding a comment to a pull request about changed resources»

The following example will add a comment to a pull request where it will list all the resources that were added, changed or deleted.

Note

If you'd like to customize it, feel free to add sample := true to the the policy and then use the Policy Workbench to see what data is available.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
package spacelift

import future.keywords.contains
import future.keywords.if
import future.keywords.in

header := sprintf("### Resource changes ([link](https://%s.app.spacelift.io/stack/%s/run/%s))\n\n![add](https://img.shields.io/badge/add-%d-brightgreen) ![change](https://img.shields.io/badge/change-%d-yellow) ![destroy](https://img.shields.io/badge/destroy-%d-red)\n\n| Action | Resource | Changes |\n| --- | --- | --- |", [input.account.name, input.run_updated.stack.id, input.run_updated.run.id, count(added), count(changed), count(deleted)])

addedresources := concat("\n", added)
changedresources := concat("\n", changed)
deletedresources := concat("\n", deleted)

added contains row if {
  some x in input.run_updated.run.changes

  row := sprintf("| Added | `%s` | <details><summary>Value</summary>`%s`</details> |", [x.entity.address, x.entity.data.values])
  x.action == "added"
  x.entity.entity_type == "resource"
}

changed contains row if {
  some x in input.run_updated.run.changes

  row := sprintf("| Changed | `%s` | <details><summary>New value</summary>`%s`</details> |", [x.entity.address, x.entity.data.values])
  x.entity.entity_type == "resource"

  any([x.action == "changed", x.action == "destroy-Before-create-replaced", x.action == "create-Before-destroy-replaced"])
}

deleted contains row if {
  some x in input.run_updated.run.changes
  row := sprintf("| Deleted | `%s` | :x: |", [x.entity.address])
  x.entity.entity_type == "resource"
  x.action == "deleted"
}

pull_request contains {"commit": input.run_updated.run.commit.hash, "body": replace(replace(concat("\n", [header, addedresources, changedresources, deletedresources]), "\n\n\n", "\n"), "\n\n", "\n")} if {
  input.run_updated.run.state == "FINISHED"
  input.run_updated.run.type == "PROPOSED"
}