Task configurations API reference

Task configurations define the enforcement level, stages of evaluation, and associated projects for HCP Terraform tasks. This page lists API endpoints to manage task configurations.

Required permissions

To interact with tasks on an organization, you need the Manage Run Tasks permission.

Task configuration owners

Every task configuration requires an owner, which determines the level at which the task configuration is applied. Currently, the only owner type that is supported is Organization owners. That is to say, the task configuration must be owned by the organization.

There can be only one task configuration mapping between a task and its owner.

Global vs targeted configurations

Every task configuration can have a set of targets to which it is associated. For example, a task configuration can be associated to many projects. However, the allowed targets are determined by both the Owner and the global value. The following rules are applied:

For an organization owned task
- A global value of true;
  - Is applied to every Project and Workspace
- A global value of false;
  - Is applied to targeted Projects supplied through the projects relationships
    - Is applied to all workspaces within each targeted Project

Create a task config

POST /organization/:organization_name/task-configs

Parameter	Description
`:organization_name`	The name of the organization that the task config is being created within.

Status	Response	Reason
201	JSON API document (`type: "task-configs"`)	Successfully created a task configuration
404	JSON API error object	Task not found, or user unauthorized to perform action
422	JSON API error object	Malformed request body (missing attributes, wrong types, etc.)

Request body

This POST endpoint requires a JSON object with the following properties as a request payload.

Properties without a default value are required unless otherwise specified.

Key path	Type	Description
`data.type`	string	Must be `"task-configs"`.
`data.attributes.global`	string	`true` to apply to every project within the owning organization; `false` will apply to projects listed in the `projects` attribute, and all workspaces within each of these projects. See: Global vs Targeted Configurations
`data.attributes.enforcement-level`	string	The enforcement level of the task configuration. Must be `"advisory"` or `"mandatory"`.
`data.attributes.allowed-stages`	array	An array of strings representing the stages of the run lifecycle when the task should begin. Must be one or more of `"pre_plan"`, `"post_plan"`, `"pre_apply"`, or `"post_apply"`.
`data.relationships.owner.data.id`	string	The ID of the organization that owns the task configuration.
`data.relationships.owner.data.type`	string	Must be `organization`.
`data.relationships.task.data.id`	string	The id of the task the configuration connects to.
`data.relationships.task.data.type`	string	Must be `"tasks"`.
`data.relationships.projects.data`	list of objects	Specifies a list of projects to associated to the task configuration. See: Global vs Targeted Configurations
`data.relationships.projects.data.type`	string	Must be `projects` for each object.
`data.relationships.projects.data.id`	string	The id of the project to associate.

Sample payload

The following sample payload shows a task configuration that is globally applied.

{
  "data": {
    "type": "task-configs",
    "attributes": {
      "global": true,
      "enforcement-level": "mandatory",
      "allowed-stages": ["pre_plan"]
    },
    "relationships": {
      "task": {
        "data": {
          "id": "task-7oD7doVTQdAFnMLV",
          "type": "tasks"
        }
      },
      "owner": {
        "data": {
          "id": "my-organization",
          "type": "organizations"
        }
      }
    }
  }
}

The following sample payload shows a task configuration that is targeted to specific projects.

{
  "data": {
    "type": "task-configs",
    "attributes": {
      "global": false,
      "enforcement-level": "mandatory",
      "allowed-stages": ["pre_plan"]
    },
    "relationships": {
      "task": {
        "data": {
          "id": "task-7oD7doVTQdAFnMLV",
          "type": "tasks"
        }
      },
      "owner": {
        "data": {
          "id": "my-organization",
          "type": "organizations"
        }
      },
      "projects": {
        "data": [
          {
            "id": "prj-jT92VLSFpv8FwKtc",
            "type": "projects"
          }
        ]
      }
    }
  }
}

Sample request

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request POST \
  --data @payload.json \
  https://app.terraform.io/api/v2/organizations/:organization_name/task-configs

Sample response

{
  "data": {
    "id": "taskcfg-3oF7doSTQdAFnMLK",
    "type": "task-configs",
    "attributes": {
      "global": false,
      "enforcement-level": "mandatory",
      "allowed-stages": ["pre_plan"]
    },
    "relationships": {
      "owner": {
        "data": {
          "id": "my-organization",
          "type": "organizations"
        }
      },
      "task": {
        "data": {
          "id": "task-7oD7doVTQdAFnMLV",
          "type": "tasks"
        }
      },
      "projects": {
        "data": [
          {
            "id": "prj-jT92VLSFpv8FwKtc",
            "type": "projects"
          }
        ]
      }
    }
  }
}

Update a task config

PATCH /task-configs/:id

Parameter	Description
`:id`	The id of the task configuration to update.

Status	Response	Reason
201	JSON API document (`type: "task-configs"`)	Successfully updated a task configuration
404	JSON API error object	Task configuration not found, or user unauthorized to perform action
422	JSON API error object	Malformed request body (missing attributes, wrong types, etc.)

Request body

This PATCH endpoint requires a JSON object with the following properties as a request payload.

Properties without a default value are required unless otherwise specified.

Key path	Type	Description
`data.type`	string	Must be `"task-configs"`.
`data.id`	string	The id of the task configuration to be updated.
`data.attributes.global`	string	Is this task configuration globally applied. See: Global vs Targeted Configurations
`data.attributes.enforcement-level`	string	The enforcement level of the task configuration. Must be `"advisory"` or `"mandatory"`.
`data.attributes.allowed-stages`	array	An array of strings representing the stages of the run lifecycle when the task should begin. Must be one or more of `"pre_plan"`, `"post_plan"`, `"pre_apply"`, or `"post_apply"`.
`data.relationships.projects.data`	list of objects	Specifies a list of projects to associated to the task configuration. See: Global vs Targeted Configurations
`data.relationships.projects.data.type`	string	Must be `projects` for each object.
`data.relationships.projects.data.id`	string	The id of the project to associate.

Sample payload

The following sample payload shows a task configuration that is globally applied.

{
  "data": {
    "type": "task-configs",
    "id": "taskcfg-3oF7doSTQdAFnMLK",
    "attributes": {
      "global": true,
      "enforcement-level": "mandatory",
      "allowed-stages": ["pre_plan"]
    }
  }
}

The following sample payload shows a task configuration that is targeted to specific projects.

{
  "data": {
    "type": "task-configs",
    "id": "taskcfg-3oF7doSTQdAFnMLK",
    "attributes": {
      "global": false,
      "enforcement-level": "mandatory",
      "allowed-stages": ["pre_plan"]
    },
    "relationships": {
      "projects": {
        "data": [
          {
            "id": "prj-jT92VLSFpv8FwKtc",
            "type": "projects"
          }
        ]
      }
    }
  }
}

Sample request

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request PATCH \
  --data @payload.json \
  https://app.terraform.io/api/v2/organizations/:organization_name/task-configs

Sample response

{
  "data": {
    "id": "taskcfg-3oF7doSTQdAFnMLK",
    "type": "task-configs",
    "attributes": {
      "global": false,
      "enforcement-level": "mandatory",
      "allowed-stages": ["pre_plan"]
    },
    "relationships": {
      "owner": {
        "data": {
          "id": "my-organization",
          "type": "organizations"
        }
      },
      "task": {
        "data": {
          "id": "task-7oD7doVTQdAFnMLV",
          "type": "tasks"
        }
      },
      "projects": {
        "data": [
          {
            "id": "prj-jT92VLSFpv8FwKtc",
            "type": "projects"
          }
        ]
      }
    }
  }
}

List task configs

GET /organizations/:organization_name/task-configs

Parameter	Description
`:organization_name`	The organization to list task configs for.

Status	Response	Reason
200	JSON API document (`type: "tasks"`)	Request was successful
404	JSON API error object	Organization not found, or user unauthorized to perform action

Query parameters

This endpoint supports pagination with standard URL query parameters. Remember to percent-encode [ as %5B and ] as %5D if your tooling doesn't automatically encode URLs.

Parameter	Description
`filter[target_type]`	In combination with `filter[target_id]`, filters task configs to those that have a specific target. Must be `"project"`.
`filter[target_id]`	In combination with `filter[target_type]`, filters task configs to a specific target. Must be a project id.
`filter[task_category]`	Optional. Filters task configs to only include the task category. Currently only `hook` is supported.

Sample request

curl \
  --header "Authorization: Bearer $TOKEN" \ 
  https://app.terraform.io/api/v2/organizations/my-organization/task-configs?filter%5Btarget_id%5D%3Dprj-WsVcWRr7SfxRci1v%26filter%5Btarget_type%5D%3Dproject

Sample response

{
  "data": [
    {
      "id": "taskcfg-3oF7doSTQdAFnMLK",
      "type": "task-configs",
      "attributes": {
        "global": false,
        "enforcement-level": "mandatory",
        "allowed-stages": ["pre_plan"]
      },
      "relationships": {
        "owner": {
          "data": {
            "id": "my-organization",
            "type": "organizations"
          }
        },
        "task": {
          "data": {
            "id": "task-7oD7doVTQdAFnMLV",
            "type": "tasks"
          }
        },
        "projects": {
          "data": [
            {
              "id": "prj-jT92VLSFpv8FwKtc",
              "type": "projects"
            }
          ]
        }
      }
    }
  ],
  "links": {
    "self": "https://app.terraform.io/api/v2/organizations/my-organization/task-configs?page%5Bnumber%5D=1&page%5Bsize%5D=20",
    "first": "https://app.terraform.io/api/v2/organizations/my-organization/task-configs?page%5Bnumber%5D=1&page%5Bsize%5D=20",
    "prev": null,
    "next": null,
    "last": "https://app.terraform.io/api/v2/organizations/my-organization/task-configs?page%5Bnumber%5D=1&page%5Bsize%5D=20"
  },
  "meta": {
    "pagination": {
      "current-page": 1,
      "page-size": 20,
      "prev-page": null,
      "next-page": null,
      "total-pages": 1,
      "total-count": 1
    }
  }
}