Environment Variables

Environment variables play a crucial role in configuring and customizing Terrateam workflows and hooks. Terrateam provides a set of built-in environment variables that you can use to access information about the current workflow execution context and the results of Terrateam operations. Additionally, you can define your own custom environment variables to store and pass data between different steps and stages of your Terrateam pipelines.

Built-in Environment Variables

Terrateam provides the following built-in environment variables:

Workflow Environment Variables

Name	Description
`TERRATEAM_PLAN_FILE`	The path to the generated Terraform plan file.
`TERRATEAM_DIR`	The working directory relative to the root of the repository.
`TERRATEAM_WORKSPACE`	The Terraform workspace being executed against.
`TERRATEAM_ROOT`	The absolute path to the root of your checked-out repository.

Post-hook Environment Variables

Name	Description
`TERRATEAM_RESULTS_FILE`	The path to a JSON file that contains the results of all executed dirspaces.

Expand for example TERRATEAM_RESULTS_FILE

{
  "dirspaces": [
      {
          "path": "database",
          "workspace": "default",
          "success": true,
          "outputs": [
              {
                  "workflow_step": {
                      "type": "run",
                      "cmd": [
                          "tofu",
                          "init"
                      ],
                      "exit_code": 0
                  },
                  "success": true,
                  "outputs": {
                      "output_key": "init",
                      "text": "\r                                                                           0.1%\r######################################################################## 100.0%\n\nInitializing the backend...\n\nInitializing provider plugins...\n- Finding latest version of hashicorp/null...\n- Installing hashicorp/null v3.2.2...\n- Installed hashicorp/null v3.2.2 (signed, key ID 0C0AF313E5FD9F80)\n\nProviders are signed by their developers.\nIf you'd like to know more about provider signing, you can read about it here:\nhttps://opentofu.org/docs/cli/plugins/signing/\n\nOpenTofu has created a lock file .terraform.lock.hcl to record the provider\nselections it made above. Include this file in your version control repository\nso that OpenTofu can guarantee to make the same selections by default when\nyou run \"tofu init\" in the future.\n\nOpenTofu has been successfully initialized!\n"
                  }
              },
              {
                  "workflow_step": {
                      "type": "plan"
                  },
                  "success": true,
                  "outputs": {
                      "plan": "\nOpenTofu used the selected providers to generate the following execution\nplan. Resource actions are indicated with the following symbols:\n  + create\n\nOpenTofu will perform the following actions:\n\n  # null_resource.foo will be created\n  + resource \"null_resource\" \"foo\" {\n      + id = (known after apply)\n    }\n\nPlan: 1 to add, 0 to change, 0 to destroy.\n",
                      "plan_text": "\nOpenTofu used the selected providers to generate the following execution\nplan. Resource actions are indicated with the following symbols:\n  + create\n\nOpenTofu will perform the following actions:\n\n  # null_resource.foo will be created\n  + resource \"null_resource\" \"foo\" {\n      + id = (known after apply)\n    }\n\nPlan: 1 to add, 0 to change, 0 to destroy.\n",
                      "has_changes": true
                  }
              }
          ]
      }
  ],
  "overall": {
      "success": true
  }
}

GitHub Actions Environment Variables

In addition to the Terrateam-specific environment variables, you also have access to the default environment variables provided by GitHub Actions. Refer to the GitHub documentation for a complete list of available variables.

Custom Environment Variables

Terrateam allows you to define your own custom environment variables in your workflows and hooks. You can use custom environment variables to store and pass data between different steps, set configuration options, or provide dynamic values based on the execution context.

Defining Custom Environment Variables in Workflows

To define custom environment variables in your Terrateam workflows, you can use the env step type. Here’s an example workflow configuration that sets a custom environment variable:

workflows:
  - tag_query: ""
    plan:
      - type: env
        name: MY_CUSTOM_VAR
        cmd: ['echo', 'Hello, World!']
      - type: run
        cmd: ['echo', 'The value of MY_CUSTOM_VAR is: $MY_CUSTOM_VAR']

In this example, the env step sets a custom environment variable named MY_CUSTOM_VAR with the value “Hello, World!“. The subsequent run step can then access the value of MY_CUSTOM_VAR using the $ prefix.

Defining Custom Environment Variables in Hooks

Similarly, you can define custom environment variables in your Terrateam hooks using the env hook type. Here’s an example hook configuration that sets a custom environment variable:

hooks:
  plan:
    pre:
      - type: env
        name: MY_HOOK_VAR
        cmd: ['echo', 'Hello from the pre-plan hook!']
    post:
      - type: run
        cmd: ['echo', 'The value of MY_HOOK_VAR is: $MY_HOOK_VAR']

In this example, the env hook in the pre section of the plan hook sets a custom environment variable named MY_HOOK_VAR with the value “Hello from the pre-plan hook!“. The run hook in the post section can then access the value of MY_HOOK_VAR.

Using Custom Environment Variables

Once you have defined your custom environment variables, you can use them in your Terrateam configurations and scripts by referencing them with the $ prefix followed by the variable name. For example:

workflows:
  - tag_query: ""
    plan:
      - type: run
        cmd: ['echo', 'The value of MY_CUSTOM_VAR is: $MY_CUSTOM_VAR']

In this example, the $MY_CUSTOM_VAR variable will be expanded to the actual value of the MY_CUSTOM_VAR environment variable during execution.

Best Practices

When using environment variables, keep the following best practices in mind:

Use meaningful and descriptive names for your own custom environment variables to avoid conflicts with Terrateam’s built-in variables or other system variables.
Be cautious when using environment variables to store sensitive information, such as secrets or credentials. Instead, consider using secure mechanisms like Terrateam’s integration with GitHub Secrets or a secrets management system.
Ensure that your scripts and configurations handle missing or empty environment variables gracefully to avoid unexpected errors or behavior.