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 with associated regular expressions that match branch names.

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 regular expression that matches the corresponding branch name.The dirs section defines static tags for specific directories in your repository.

Tag Definition

Each tag in the top-level tags configuration is defined as a key-value pair. The key represents the tag name, and the value is a map of tag values and their corresponding regular expressions.

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
        method: source
        cmd: ['echo', 'main']
      - type: init
      - type: plan
    apply:
      - type: env
        method: source
        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 Tags with Regular Expressions

Terrateam uses regular expressions to match tags against the defined values in the top-level tags configuration. This allows for flexible and powerful matching capabilities. In the example configuration, the regular expressions 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 regular expressions to match your specific branch naming conventions or other criteria.

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.