• Stars
    star
    619
  • Rank 72,496 (Top 2 %)
  • Language
    Go
  • License
    MIT License
  • Created over 6 years ago
  • Updated almost 2 years ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

A CLI command to parse Terraform execution result and notify it to GitHub

tfnotify

tfnotify parses Terraform commands' execution result and applies it to an arbitrary template and then notifies it to GitHub comments etc.

Motivation

There are commands such as plan and apply on Terraform command, but many developers think they would like to check if the execution of those commands succeeded. Terraform commands are often executed via CI like Circle CI, but in that case you need to go to the CI page to check it. This is very troublesome. It is very efficient if you can check it with GitHub comments or Slack etc. You can do this by using this command.

Installation

Grab the binary from GitHub Releases (Recommended)

or

$ go get -u github.com/mercari/tfnotify

What tfnotify does

  1. Parse the execution result of Terraform
  2. Bind parsed results to Go templates
  3. Notify it to any platform (e.g. GitHub) as you like

Detailed specifications such as templates and notification destinations can be customized from the configuration files (described later).

Usage

Basic

tfnotify is just CLI command. So you can run it from your local after grabbing the binary.

Basically tfnotify waits for the input from Stdin. So tfnotify needs to pipe the output of Terraform command like the following:

$ terraform plan | tfnotify plan

For plan command, you also need to specify plan as the argument of tfnotify. In the case of apply, you need to do apply. Currently supported commands can be checked with tfnotify --help.

Configurations

When running tfnotify, you can specify the configuration path via --config option (if it's omitted, it defaults to {.,}tfnotify.y{,a}ml).

The example settings of GitHub and GitHub Enterprise, Slack, Typetalk are as follows. Incidentally, there is no need to replace TOKEN string such as $GITHUB_TOKEN with the actual token. Instead, it must be defined as environment variables in CI settings.

template of Go can be used for template. The templates can be used in tfnotify.yaml are as follows:

Placeholder Usage
{{ .Title }} Like ## Plan result
{{ .Message }} A string that can be set from CLI with --message option
{{ .Result }} Matched result by parsing like Plan: 1 to add or No changes
{{ .Body }} The entire of Terraform execution result
{{ .Link }} The link of the build page on CI

On GitHub, tfnotify can also put a warning message if the plan result contains resource deletion (optional).

Template Examples

For GitHub
---
ci: circleci
notifier:
  github:
    token: $GITHUB_TOKEN
    repository:
      owner: "mercari"
      name: "tfnotify"
terraform:
  fmt:
    template: |
      {{ .Title }}

      {{ .Message }}

      {{ .Result }}

      {{ .Body }}
  plan:
    template: |
      {{ .Title }} <sup>[CI link]( {{ .Link }} )</sup>
      {{ .Message }}
      {{if .Result}}
      <pre><code>{{ .Result }}
      </pre></code>
      {{end}}
      <details><summary>Details (Click me)</summary>

      <pre><code>{{ .Body }}
      </pre></code></details>
  apply:
    template: |
      {{ .Title }}
      {{ .Message }}
      {{if .Result}}
      <pre><code>{{ .Result }}
      </pre></code>
      {{end}}
      <details><summary>Details (Click me)</summary>

      <pre><code>{{ .Body }}
      </pre></code></details>

If you would like to let tfnotify warn the resource deletion, add when_destroy configuration as below.

---
# ...
terraform:
  # ...
  plan:
    template: |
      {{ .Title }} <sup>[CI link]( {{ .Link }} )</sup>
      {{ .Message }}
      {{if .Result}}
      <pre><code>{{ .Result }}
      </pre></code>
      {{end}}
      <details><summary>Details (Click me)</summary>

      <pre><code>{{ .Body }}
      </pre></code></details>
    when_destroy:
      template: |
        ## :warning: WARNING: Resource Deletion will happen :warning:

        This plan contains **resource deletion**. Please check the plan result very carefully!
  # ...

You can also let tfnotify add a label to PRs depending on the terraform plan output result. Currently, this feature is for Github labels only.

---
# ...
terraform:
  # ...
  plan:
    template: |
      {{ .Title }} <sup>[CI link]( {{ .Link }} )</sup>
      {{ .Message }}
      {{if .Result}}
      <pre><code>{{ .Result }}
      </pre></code>
      {{end}}
      <details><summary>Details (Click me)</summary>

      <pre><code>{{ .Body }}
      </pre></code></details>
    when_add_or_update_only:
      label: "add-or-update"
    when_destroy:
      label: "destroy"
    when_no_changes:
      label: "no-changes"
    when_plan_error:
      label: "error"
  # ...

Sometimes you may want not to HTML-escape Terraform command outputs. For example, when you use code block to print command output, it's better to use raw characters instead of character references (e.g. -/+ -> -/&#43;, " -> &#34;).

You can disable HTML escape by adding use_raw_output: true configuration. With this configuration, Terraform doesn't HTML-escape any Terraform output.

---
# ...
terraform:
  use_raw_output: true
  # ...
  plan:
    template: |
      {{ .Title }} <sup>[CI link]( {{ .Link }} )</sup>
      {{ .Message }}
      {{if .Result}}
      ```
      {{ .Result }}
      ```
      {{end}}
      <details><summary>Details (Click me)</summary>

      ```
      {{ .Body }}
      ```
  # ...
For GitHub Enterprise
---
ci: circleci
notifier:
  github:
    token: $GITHUB_TOKEN
    base_url: $GITHUB_BASE_URL # Example: https://github.example.com/api/v3
    repository:
      owner: "mercari"
      name: "tfnotify"
terraform:
  fmt:
    template: |
      {{ .Title }}

      {{ .Message }}

      {{ .Result }}

      {{ .Body }}
  plan:
    template: |
      {{ .Title }} <sup>[CI link]( {{ .Link }} )</sup>
      {{ .Message }}
      {{if .Result}}
      <pre><code>{{ .Result }}
      </pre></code>
      {{end}}
      <details><summary>Details (Click me)</summary>

      <pre><code>{{ .Body }}
      </pre></code></details>
  apply:
    template: |
      {{ .Title }}
      {{ .Message }}
      {{if .Result}}
      <pre><code>{{ .Result }}
      </pre></code>
      {{end}}
      <details><summary>Details (Click me)</summary>

      <pre><code>{{ .Body }}
      </pre></code></details>
For GitLab
---
ci: gitlabci
notifier:
  gitlab:
    token: $GITLAB_TOKEN
    base_url: $GITLAB_BASE_URL
    repository:
      owner: "mercari"
      name: "tfnotify"
terraform:
  fmt:
    template: |
      {{ .Title }}

      {{ .Message }}

      {{ .Result }}

      {{ .Body }}
  plan:
    template: |
      {{ .Title }} <sup>[CI link]( {{ .Link }} )</sup>
      {{ .Message }}
      {{if .Result}}
      <pre><code> {{ .Result }}
      </pre></code>
      {{end}}
      <details><summary>Details (Click me)</summary>
      <pre><code> {{ .Body }}
      </pre></code></details>
  apply:
    template: |
      {{ .Title }}
      {{ .Message }}
      {{if .Result}}
      <pre><code> {{ .Result }}
      </pre></code>
      {{end}}
      <details><summary>Details (Click me)</summary>
      <pre><code> {{ .Body }}
      </pre></code></details>
For Slack
---
ci: circleci
notifier:
  slack:
    token: $SLACK_TOKEN
    channel: $SLACK_CHANNEL_ID
    bot: $SLACK_BOT_NAME
terraform:
  plan:
    template: |
      {{ .Message }}
      {{if .Result}}
      ```
      {{ .Result }}
      ```
      {{end}}
      ```
      {{ .Body }}
      ```

Sometimes you may want not to HTML-escape Terraform command outputs. For example, when you use code block to print command output, it's better to use raw characters instead of character references (e.g. -/+ -> -/&#43;, " -> &#34;).

You can disable HTML escape by adding use_raw_output: true configuration. With this configuration, Terraform doesn't HTML-escape any Terraform output.

---
# ...
terraform:
  use_raw_output: true
  # ...
  plan:
  # ...
For Typetalk
---
ci: circleci
notifier:
  typetalk:
    token: $TYPETALK_TOKEN
    topic_id: $TYPETALK_TOPIC_ID
terraform:
  plan:
    template: |
      {{ .Message }}
      {{if .Result}}
      ```
      {{ .Result }}
      ```
      {{end}}
      ```
      {{ .Body }}
      ```

Supported CI

Currently, supported CI are here:

  • Circle CI
  • Travis CI
  • AWS CodeBuild
  • TeamCity
  • Drone
  • Jenkins
  • GitLab CI
  • GitHub Actions
  • Google Cloud Build

Private Repository Considerations

GitHub private repositories require the repo and write:discussion permissions.

Jenkins Considerations

  • Plugin
  • Environment Variable
    • PULL_REQUEST_NUMBER or PULL_REQUEST_URL are required to set by user for Pull Request Usage

Google Cloud Build Considerations

  • These environment variables are needed to be set using substitutions
    • COMMIT_SHA
    • BUILD_ID
    • PROJECT_ID
    • _PR_NUMBER
    • _REGION
  • Recommended trigger events
    • terraform plan: Pull request
    • terraform apply: Push to branch

Committers

Contribution

Please read the CLA below carefully before submitting your contribution.

https://www.mercari.com/cla/

License

Copyright 2018 Mercari, Inc.

Licensed under the MIT License.

More Repositories

1

ml-system-design-pattern

System design patterns for machine learning
2,221
star
2

engineer-vocabulary-list

Engineer Vocabulary List in Japanese/English
1,770
star
3

gaurun

General push notification server in Go
Go
931
star
4

production-readiness-checklist

Production readiness checklist used for Mercari and Merpay microservices
844
star
5

Mew

The framework that support making MicroViewController.
Swift
485
star
6

tortoise

Tortoise: Shell-Shockingly-Good Kubernetes Autoscaling
Go
380
star
7

grpc-http-proxy

A reverse proxy server which translate JSON HTTP requests to gRPC calls based on protoreflect
Go
371
star
8

go-circuitbreaker

A context aware circuit breaker library in Go.
Go
358
star
9

mercari-microservices-example

Go
327
star
10

QRScanner

A simple QR Code scanner framework for iOS. Provides a similar scan effect to ios13+.
Swift
313
star
11

grpc-federation

gRPC Federation generates a gRPC server by writing a custom option in Protocol Buffers
Go
238
star
12

go-httpdoc

Golang package for generating API documentation from httptest. See example output
Go
228
star
13

datastore

(AE|Cloud) Datastore Wrapper
Go
214
star
14

mercari-slack-guidelines

Slack guidelines of Mercari.
202
star
15

ShimmerView

ShimmerView is a collection of APIs to construct Skelton View + Shimmering Effect type loading indicator on UIKit and SwiftUI.
Swift
195
star
16

mercari-engineering-ladder

Mercari's Expectations for Engineers in Various Stages of Their Career
163
star
17

mtc2018-app

The Official Conference App for Mercari Tech Conf 2018
Dart
134
star
18

go-grpc-interceptor

gRPC server insterceptor for golang
Go
124
star
19

go-dnscache

Go package for caching DNS lookup results in memory.
Go
121
star
20

certificate-expiry-monitor-controller

Certificate Expiry Monitor Controller monitors the expiration of TLS certificates used in Ingress.
Go
117
star
21

souzoh-recruitment

117
star
22

mtc2018-web

Mercari Tech Conf 2018
TypeScript
100
star
23

BottomHalfModal

A customizable bottom half modal used in merpay
Swift
95
star
24

kubetempura

Go
93
star
25

widebullet

Widebullet is an API gateway with JSON-RPC
Go
91
star
26

dietcube

The world super fly weight & flexible PHP framework.
PHP
79
star
27

docker-appengine-go

Projects has been moved
Dockerfile
74
star
28

spanner-autoscaler

Kubernetes Operator for Cloud Spanner autoscaling
Go
73
star
29

RxReduxK

Micro-framework for Redux implemented in Kotlin
Kotlin
67
star
30

testdeck

Testdeck is a framework for integration, end-to-end (E2E), and security testing of gRPC microservices written in Golang.
Go
65
star
31

DataflowTemplate

Mercari Dataflow Template
Java
64
star
32

go-emv-code

EMV® QR Code Encoder/Decoder for Go.
Go
64
star
33

hcledit

Go package to edit HCL configuration
Go
49
star
34

go-httpstats

Go package for reporting HTTP stats
Go
44
star
35

RemoteDataK

Algebraic data type (ADT) to represent the state of data that is loading from/to remote sources/destinations
Kotlin
44
star
36

fractal

Swift
36
star
37

go-bps

Go package to manage the basis point
Go
36
star
38

mtc2018-app-SwiftUI

Project to rewrite MTC2018 App by SwiftUI
Swift
33
star
39

siberi-android

A/B testing library for Android
Java
33
star
40

BalloonView

Makes balloon-like view with an arrow pointing to another view. Useful for onboarding tutorials
Swift
25
star
41

DataflowTemplates

Convenient Dataflow pipelines for transforming data between cloud data sources
Java
24
star
42

yasashii-wfh-comms

yasashii-WFH-Communication-Best-Practices
19
star
43

mercari-ml-merrec-pub-us

Python
18
star
44

swiftui-chart

Swift
17
star
45

honyakubot

Slack translation bot
Swift
14
star
46

github-app-token-generator

A simple github action written in go to retrieve an installation access token for an app installed into an organization.
Go
14
star
47

github-token-app

Github Token App is a package for generating short lived github tokens (expires in 1 hour) with minimum necessary permissions.
Python
13
star
48

terraform-provider-spinnaker

A Spinnaker provider for Terraform
Go
13
star
49

composer-diff-plugin

composer plugin to show library version diff at "composer update".
PHP
12
star
50

CFQIRBM

Collaborative Filtering Quantum Infinite Restricted Boltzmann Machine
Jupyter Notebook
12
star
51

Remi

Mascot
10
star
52

terraform-provider-openpgp

Terraform OpenPGP provider
Go
8
star
53

imageflux-cli

Go
8
star
54

eslint-config-mercari

JavaScript
7
star
55

universal-apk-plugin

Gradle Plugin allowing to create an Universal APK for debug purpose.
Kotlin
6
star
56

mkdocs-git-snippet

Python
6
star
57

commitver

Derive a semver version from the commit history in any repo.
Shell
6
star
58

kafka-connect-transform-kryptonite-gcp

Java
5
star
59

proto-to-type

A Node.js library that generates type definition for TypeScript from Protocol Buffer
TypeScript
4
star
60

stylelint-config-mercari

The shareable config for @stylelint by @mercari.
CSS
3
star
61

merlin

Merlin is an agent sends out alerts when kubernetes resources are misconfigured or not comply with custom rules.
Go
3
star
62

modserver

modserver is a simple Go module server.
Go
3
star
63

extract-primitives

extract-primitives extracts primitive values from TypeScript's declaration file(.d.ts).
TypeScript
2
star
64

Whitesource-Scan-Action

Shell
2
star
65

terraform-exfiltration-lab

HCL
2
star
66

merpay-netpayment-sdk-php

Merpay Online Payments SDK for PHP
PHP
1
star
67

pubsubloader

Archived. You can find a better way on https://github.com/GoogleCloudPlatform/DataflowTemplates/tree/master/v2/streaming-data-generator. Cloud Dataflow based Cloud Pub/Sub load generator and integration tester with custom data
Scala
1
star