HCP Terraform の Workspace VCS Triggers 設定と API レスポンスの関係性

HCP Terraform の Workspace 設定には、Version Control ページ内に VCS Triggers という設定欄があり、その中に Automatic Run Triggering という設定があります。
この設定では、VCS の変更に対して自動的に Run を実行するトリガー条件を設定できます。
本記事では、この設定内容と HCP Terraform の API レスポンスの関係性を整理します。

## 対象 API

本記事では、以下の List workspaces API のレスポンスを確認します。

https://developer.hashicorp.com/terraform/cloud-docs/api-docs/workspaces#list-workspaces

## Automatic Run Triggering の設定と API レスポンスの対応

### 1. Always trigger runs

| API レスポンス属性                          | 値        |
| ------------------------------------------- | --------- |
| .data.[].attributes."file-triggers-enabled" | **false** |
| .data.[].attributes."vcs-repo"."tags-regex" | **null**  |
| .data.[].attributes."trigger-prefixes"      | []        |
| .data.[].attributes."trigger-patterns"      | []        |

```json
{
  "data": [
    {
      "id": "ws-a",
      "type": "workspaces",
      "attributes": {
        "vcs-repo": {
          "tags-regex": null
        },
        "file-triggers-enabled": false,
        "trigger-prefixes": [],
        "trigger-patterns": []
        // その他の属性...
      }
    }
  ],
  "links": {},
  "meta": {}
}
```

### 2. Only trigger runs when files in specified paths change

#### a. Patterns を設定する場合

| API レスポンス属性                          | 値                                                                                                                                                                  |
| ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| .data.[].attributes."file-triggers-enabled" | **true**                                                                                                                                                            |
| .data.[].attributes."vcs-repo"."tags-regex" | null                                                                                                                                                                |
| .data.[].attributes."trigger-prefixes"      | **[]**                                                                                                                                                              |
| .data.[].attributes."trigger-patterns"      | **(配列形式で指定された [Glob Patterns](https://developer.hashicorp.com/terraform/cloud-docs/workspaces/settings/vcs#glob-patterns-for-automatic-run-triggering))** |

```json
{
  "data": [
    {
      "id": "ws-a",
      "type": "workspaces",
      "attributes": {
        "vcs-repo": {
          "tags-regex": null
        },
        "file-triggers-enabled": true,
        "trigger-prefixes": [],
        "trigger-patterns": (配列形式で指定された Glob Patterns),
        // その他の属性...
      }
    }
  ],
  "links": {},
  "meta": {}
}
```

#### b. Prefixes を設定する場合

| API レスポンス属性                          | 値                               |
| ------------------------------------------- | -------------------------------- |
| .data.[].attributes."file-triggers-enabled" | **true**                         |
| .data.[].attributes."vcs-repo"."tags-regex" | null                             |
| .data.[].attributes."trigger-prefixes"      | **(配列形式で指定された接頭辞)** |
| .data.[].attributes."trigger-patterns"      | **[]**                           |

```json
{
  "data": [
    {
      "id": "ws-a",
      "type": "workspaces",
      "attributes": {
        "vcs-repo": {
          "tags-regex": null
        },
        "file-triggers-enabled": true,
        "trigger-prefixes": (配列形式で指定された接頭辞),
        "trigger-patterns": [],
        // その他の属性...
      }
    }
  ],
  "links": {},
  "meta": {}
}
```

### 3. Trigger runs when a git tag is published の場合

#### a. Default (e.g. `12.33.4456`) を設定する場合

| API レスポンス属性                          | 値                     |
| ------------------------------------------- | ---------------------- |
| .data.[].attributes."file-triggers-enabled" | **false**              |
| .data.[].attributes."vcs-repo"."tags-regex" | **"^\\d+.\\d+.\\d+$"** |
| .data.[].attributes."trigger-prefixes"      | []                     |
| .data.[].attributes."trigger-patterns"      | []                     |

```json
{
  "data": [
    {
      "id": "ws-a",
      "type": "workspaces",
      "attributes": {
        "vcs-repo": {
          "tags-regex": "^\\d+.\\d+.\\d+$"
        },
        "file-triggers-enabled": false,
        "trigger-prefixes": [],
        "trigger-patterns": []
        // その他の属性...
      }
    }
  ],
  "links": {},
  "meta": {}
}
```

#### b. Version contains a prefix (e.g. `v-12.33.4456` ) を設定する場合

| API レスポンス属性                          | 値                    |
| ------------------------------------------- | --------------------- |
| .data.[].attributes."file-triggers-enabled" | **false**             |
| .data.[].attributes."vcs-repo"."tags-regex" | **"\\d+.\\d+.\\d+$"** |
| .data.[].attributes."trigger-prefixes"      | []                    |
| .data.[].attributes."trigger-patterns"      | []                    |

```json
{
  "data": [
    {
      "id": "ws-a",
      "type": "workspaces",
      "attributes": {
        "vcs-repo": {
          "tags-regex": "\\d+.\\d+.\\d+$"
        },
        "file-triggers-enabled": false,
        "trigger-prefixes": [],
        "trigger-patterns": []
        // その他の属性...
      }
    }
  ],
  "links": {},
  "meta": {}
}
```

#### c. Version contains a suffix (e.g. `12.33.4456-v` ) を設定する場合

| API レスポンス属性                          | 値                    |
| ------------------------------------------- | --------------------- |
| .data.[].attributes."file-triggers-enabled" | **false**             |
| .data.[].attributes."vcs-repo"."tags-regex" | **"^\\d+.\\d+.\\d+"** |
| .data.[].attributes."trigger-prefixes"      | []                    |
| .data.[].attributes."trigger-patterns"      | []                    |

```json
{
  "data": [
    {
      "id": "ws-a",
      "type": "workspaces",
      "attributes": {
        "vcs-repo": {
          "tags-regex": "^\\d+.\\d+.\\d+"
        },
        "file-triggers-enabled": false,
        "trigger-prefixes": [],
        "trigger-patterns": []
        // その他の属性...
      }
    }
  ],
  "links": {},
  "meta": {}
}
```

#### d. Custom Regular Expression を設定する場合

| API レスポンス属性                          | 値                     |
| ------------------------------------------- | ---------------------- |
| .data.[].attributes."file-triggers-enabled" | **false**              |
| .data.[].attributes."vcs-repo"."tags-regex" | **(設定した正規表現)** |
| .data.[].attributes."trigger-prefixes"      | []                     |
| .data.[].attributes."trigger-patterns"      | []                     |

```json
{
  "data": [
    {
      "id": "ws-a",
      "type": "workspaces",
      "attributes": {
        "vcs-repo": {
          "tags-regex": "(設定した正規表現)"
        },
        "file-triggers-enabled": false,
        "trigger-prefixes": [],
        "trigger-patterns": []
        // その他の属性...
      }
    }
  ],
  "links": {},
  "meta": {}
}
```