DOCSEARCHbyAlgolia
Submit Docs

tfcmt Documentation

repository·main·Indexed 19 days ago

https://github.com/suzuki-shunsuke/tfcmt

tfcmt is a notification tool for Terraform that sends updates to GitHub. A fork of tfnotify, it adds support for Terraform version 0.15 and above and provides advanced formatting capabilities. It includes a CLI with 'plan' and 'apply' commands to post Terraform operation results as comments to GitHub commits, pull requests, or issues, and supports GitHub Enterprise endpoints.

Tokens
13.7K
Snippets
57
Records
71
Agent score
63%

What's inside tfcmt

  1. Overview of tfcmt

    main

    tfcmt is a tool designed to provide notifications for Terraform operations. It is a fork of mercari/tfnotify that includes enhancements such as support for Terraform version 0.15 and above, along with advanced formatting options.

    Important Compatibility Note: tfcmt currently only supports notifications for GitHub. If you are using GitLab, you should use tfcmt-gitlab instead.

  3. Use tfcmt in CI platforms

    main

    When running in supported CI environments, tfcmt can automatically retrieve the repository owner, name, and pull request number from built-in environment variables. This allows you to omit the -owner, -repo, and -pr flags.

    Supported Platforms:

    • AWS CodeBuild
    • CircleCI
    • Drone
    • GitHub Actions
    • Google Cloud Build
    # In supported CI, you can simply run:
tfcmt plan -- terraform plan

  5. Use template variables in tfcmt

    main

    tfcmt uses Go's html/template engine. You can use several built-in variables within your templates to access Terraform output and execution metadata:

    PlaceholderDescription
    {{ .Result }}Matched result from parsing (e.g., Plan: 1 to add or No changes)
    {{ .ChangedResult }}Result of changes made outside of Terraform
    {{ .ChangeOutsideTerraform }}Result of changes made outside of Terraform
    {{ .Warning }}Captured warnings
    {{ .Link }}The link to the build page on your CI
    {{ .Vars }}Variables passed via the -var option
    {{ .Stdout }}Terraform standard output
    {{ .Stderr }}Terraform standard error
    {{ .CombinedOutput }}Combined Terraform output
    {{ .ExitCode }}Terraform exit code
    {{ .HasDestroy }}Boolean indicating if resources will be destroyed
    {{ .ErrorMessages }}A list of error messages occurring in tfcmt
    {{ .CreatedResources }}List of created resource paths (Plan only)
    {{ .UpdatedResources }}List of updated resource paths (Plan only)
    {{ .DeletedResources }}List of deleted resource paths (Plan only)
    {{ .ReplacedResources }}List of replaced resource paths (Plan only)
    {{ .MovedResources }}List of moved resource paths (Plan only)
    {{ .ImportedResources }}List of imported resources (e.g., {"Before": "path", "After": "path"}) (Plan only)

  6. Use tfcmt with supported CI platforms

    main

    tfcmt provides native support for several CI platforms by automatically mapping their built-in environment variables to tfcmt parameters.

    Supported platforms:

    • CircleCI
    • Drone
    • AWS CodeBuild
    • GitHub Actions
    • Google Cloud Build

    When running on these platforms, you do not need to manually provide the following CLI flags, as they are automatically complemented by the CI environment:

    • -owner
    • -repo
    • -pr
    • -sha
    • -build-url

  7. Hide old tfcmt comments using github-comment

    main

    To prevent comment clutter when running CI multiple times on the same Pull Request, you can use the github-comment tool.

    tfcmt embeds metadata in its comments as HTML comments, such as: <!-- github-comment: {"Command":"plan","PRNumber":70,"Program":"tfcmt","SHA1":"","Vars":{}} -->

    You can use the github-comment hide command to automatically hide these previous comments.

  8. Post Terraform plan results as GitHub comments

    main

    Use the tfcmt plan command to execute terraform plan and post the results as a comment on a GitHub Pull Request.

    tfcmt plan provides several automated features:

    1. Summary Information: Displays the number of resources to be added, changed, or destroyed.
    2. List of Changed Resources: Provides a categorized list of actions (Create, Update, Delete, Replace, Import, Move).
    3. Pull Request Labels: Automatically sets labels on the PR to indicate the plan outcome:
      • no-changes (green): No resources will change.
      • add-or-update (blue): Resources will be created or updated, but none destroyed/recreated.
      • destroy (red): Resources will be destroyed or recreated.
    4. Deletion Warning: If the plan includes resource destruction, a specific deletion warning is included in the comment to prevent unexpected deletions.
    5. Details Toggle: The full terraform plan output is available under a Details section in the comment.
    # Example command for a local environment
tfcmt -owner "$OWNER" -repo "$REPO" -pr "$PR_NUMBER" plan -- terraform plan

  9. Migrating from tfnotify to tfcmt

    main

    tfcmt is a fork of mercari/tfnotify (v0.7.0) but is not compatible with it. If you are migrating from tfnotify, be aware of the following breaking changes:

    Command Usage

    tfnotify used pipes, whereas tfcmt uses a double-dash (--) separator to wrap the Terraform command. This allows tfcmt to capture standard error and exit codes correctly.

    Old (tfnotify):

    terraform plan | tfnotify plan

    New (tfcmt):

    tfcmt plan -- terraform plan

    Configuration Changes

    • File Name: The configuration file name has changed from tfnotify.yml (or .yaml) to tfcmt.yml (or .yaml).
    • Structure: The notifier option has been removed, and the ci structure has changed.

    Template Variable Changes

    • Replace .Body with .CombinedOutput (which includes both stdout and stderr).
    • The .Message and .Title variables (and their corresponding --message and --title CLI options) have been removed. Use the -var option and the .Vars template variable instead.

    Platform Support

    tfcmt has a reduced platform footprint compared to tfnotify. It only supports:

    • CI: CircleCI, CodeBuild, CloudBuild, GitHub Actions.
    • Notifier: GitHub.

    Note: For GitLab users, use the hirosassa/tfcmt-gitlab fork instead.

    tfcmt plan -- terraform plan

  10. Run terraform apply with tfcmt apply

    main

    Use the tfcmt apply command to execute a Terraform apply and automatically post the results as a comment to a GitHub commit, pull request, or issue.

    Usage Pattern: tfcmt [<global options>] apply -- terraform apply [<terraform apply options>]

    Global Options: Commands support global options to specify the GitHub context, such as --owner, --repo, --sha, and --pr.

    $ tfcmt [<global options>] apply -- terraform apply [<terraform apply options>]

  11. Verify tfcmt binaries using slsa-verifier

    main

    You can verify the SLSA provenance of tfcmt artifacts using slsa-verifier.

    1. Install slsa-verifier (e.g., via aqua): aqua g -i slsa-framework/slsa-verifier.
    2. Download the release assets.
    3. Run slsa-verifier verify-artifact providing the provenance path, source URI, and source tag.
    # Download assets from GitHub Releases.
gh release download -R suzuki-shunsuke/tfcmt v4.14.0

# Verify an asset.
slsa-verifier verify-artifact tfcmt_darwin_arm64.tar.gz \
  --provenance-path multiple.intoto.jsonl \
  --source-uri github.com/suzuki-shunsuke/tfcmt \
  --source-tag v4.14.0

  12. Configure tfcmt for GitHub Enterprise

    main

    To use tfcmt with a GitHub Enterprise instance, you must specify the base URL and the GraphQL endpoint in your tfcmt.yaml configuration file.

    Alternatively, starting from tfcmt v4.12.0, you can use the following environment variables, which are compatible with GitHub Actions' built-in variables:

    • GITHUB_API_URL
    • GITHUB_GRAPHQL_URL
    # tfcmt.yaml
ghe_base_url: https://example.com
ghe_graphql_endpoint: https://example.com/api/graphql