tags

The tags configuration allows you to define custom labels that can be used to match and filter resources in your Terraform configuration. While the dirs key also supports tags, this documentation specifically focuses on the top-level tags key, which enables you to define tags based on dynamic criteria such as the destination branch of a pull request.

By leveraging the top-level tags key, you can create more granular and flexible workflows that adapt to the specific context of your pull requests and branches.

Default Configuration

tags: {}

Keys

Key	Type	Description
dest_branch	Map	Defines tags for destination branches. The key is the tag value and the value is a Lua pattern that is matched against the destination branch name. Produces dest_branch:<key> tags.
branch	Map	Defines tags for source branches. The key is the tag value and the value is a Lua pattern that is matched against the source branch name of the pull request. Produces branch:<key> tags.

Example Configuration

tags:
  dest_branch:
    main: '^main$'
    staging: '^staging$'
    dev: '^dev$'
dirs:
  dev:
    tags: [dev]
  staging:
    tags: [staging]
  prod:
    tags: [prod]

In this example, the tags section defines a tag called dest_branch, which has three possible values: main, staging, and dev. Each value is associated with a pattern that matches the corresponding branch name. The dirs section defines static tags for specific directories in your repository.

Source branch tags work the same way under branch:

tags:
  branch:
    hotfix: '^hotfix/'
    feature: '^feature/'

A pull request from the branch hotfix/db-timeout receives the branch:hotfix tag.

Tag Definition

Each tag in the top-level tags configuration is defined as a key-value pair. The key represents the tag name (dest_branch or branch), and the value is a map of tag values and their corresponding patterns.

Using Tags in Tag Queries

Once tags are defined in the top-level tags configuration, you can use them in tag queries to match and filter resources based on specific criteria. Tag queries are used in various parts of the Terrateam configuration, such as workflows and access control.

Example Workflow Configuration

workflows:
  - tag_query: 'dest_branch:main'
    plan:
      - type: env
        name: ENVIRONMENT
        cmd: ['echo', 'main']
      - type: init
      - type: plan
    apply:
      - type: env
        name: ENVIRONMENT
        cmd: ['echo', 'main']
      - type: init
      - type: apply

In this example, the workflow is triggered when the dest_branch tag matches the main value. The tag_query field specifies the condition that must be met for the workflow to be executed. You can also combine tags from the top-level tags configuration with tags defined in the dirs section to create more specific and targeted workflows.

Matching Branch Names with Patterns

Terrateam matches branch names against the values in the top-level tags configuration using Lua patterns. Lua patterns resemble regular expressions for simple cases: ^ anchors the start, $ anchors the end, . matches any character, and * repeats. Alternation (|) and \d-style classes are not available; use %d and similar Lua classes instead. In the example configuration, the patterns are defined as follows:

• '^main$': Matches the exact string main.
• '^staging$': Matches the exact string staging.
• '^dev$': Matches the exact string dev.

You can customize the patterns to match your specific branch naming conventions, for example '^release/' to match every branch under release/.

Considerations

When configuring tags in the top-level tags section of the Terrateam configuration, keep the following considerations in mind:

• Tags defined in the top-level tags section are dynamic and can be used to match resources based on the context of your pull requests, such as the destination branch.
• Tags defined in the dirs section are static and are assigned directly to specific directories in your repository.
• You can use tags from both the top-level tags configuration and the dirs section in combination to create more targeted and flexible workflows.