https://github.com/takescoop/terraform-cloud-workspace-action
GitHub action for managing Terraform cloud workspaces
https://github.com/takescoop/terraform-cloud-workspace-action
github-actions terraform terraform-cloud
Last synced: about 1 month ago
JSON representation
GitHub action for managing Terraform cloud workspaces
- Host: GitHub
- URL: https://github.com/takescoop/terraform-cloud-workspace-action
- Owner: TakeScoop
- License: mit
- Created: 2021-07-22T16:02:39.000Z (almost 4 years ago)
- Default Branch: master
- Last Pushed: 2025-04-10T14:09:08.000Z (about 1 month ago)
- Last Synced: 2025-04-10T15:50:03.698Z (about 1 month ago)
- Topics: github-actions, terraform, terraform-cloud
- Language: Go
- Size: 212 KB
- Stars: 1
- Watchers: 4
- Forks: 0
- Open Issues: 12
-
Metadata Files:
- Readme: README.md
- License: LICENSE.md
Awesome Lists containing this project
README
# Terraform Cloud Workspace Action
A GitHub action for managing Terraform Cloud workspaces
## Usage
```yaml
name: TFLint
on: [push]
jobs:
lint:
runs-on: ubuntu-latest
steps:
- uses: takescoop/terraform-cloud-workspace-action@v0
with:
terraform_token: "${{ secrets.TF_TOKEN }}"
terraform_organization: "my-org"
apply: "${{ github.ref == format('refs/heads/{0}', github.event.repository.default_branch) }}"
backend_config: |-
s3:
bucket: my-bucket
key: foo.tfstate
region: us-east-1
```
## Inputs
## Inputs
| parameter | description | required | default |
| - | - | - | - |
| terraform_version | Workspace Terraform version. This can be either an exact version or a version constraint (like ~> 1.0.0). | `false` | 1 |
| terraform_token | Terraform Cloud token. | `true` | |
| terraform_host | Terraform Cloud host. | `false` | app.terraform.io |
| terraform_organization | Terraform Cloud organization. | `true` | |
| tfe_provider_version | Terraform Cloud provider version. | `false` | 0.30.2 |
| name | Name of the workspace. Becomes a prefix if workspaces are passed (`${name}-${workspace}`). | `false` | ${{ github.event.repository.name }} |
| description | Terraform Cloud workspace description | `false` | ${{ github.event.repository.description }} |
| tags | YAML encoded list of tag names applied to all workspaces | `false` | |
| workspace_tags | YAML encoded map of workspace names to a list of tag names, which are applied to the specified workspace | `false` | |
| runner_terraform_version | Terraform version used in GitHub Actions to manage the workspace and related resources. | `false` | 1.1.8 |
| workspaces | YAML encoded list of workspace names. | `false` | |
| backend_config | YAML encoded backend configurations. | `false` | |
| apply | Whether to apply the proposed Terraform changes. | `true` | |
| import | Whether to import existing matching resources from the Terraform Cloud organization. | `false` | true |
| variables | YAML encoded variables to apply to all workspaces. | `false` | |
| workspace_variables | YAML encoded map of variables to apply to specific workspaces, with each key corresponding to a workspace. | `false` | |
| vcs_type | Terraform VCS type (e.g., "github"). Superseded by `vcs_token_id`. If neither are passed, no VCS integration is added. | `false` | |
| vcs_token_id | Terraform VCS client token ID. Takes precedence over `vcs_name`. If neither are passed, no VCS integration is added. | `false` | |
| vcs_repo | Repository identifier for a VCS integration. | `false` | ${{ github.repository }} |
| vcs_ingress_submodules | Whether to allow submodule ingress. | `false` | false |
| working_directory | A relative path that Terraform will execute within. Defaults to the root of your repository. | `false` | |
| agent_pool_id | ID of an agent pool to assign to the workspace. If passed, execution_mode is set to "agent". | `false` | |
| execution_mode | Execution mode to use for the workspace. | `false` | remote |
| global_remote_state | Whether all workspaces in the organization can access the workspace via remote state. | `false` | false |
| remote_state_consumer_ids | Comma separated list of workspace IDs to allow read access to the workspace outputs. | `false` | |
| auto_apply | Whether to set auto_apply on the workspace or workspaces. | `false` | true |
| queue_all_runs | Whether the workspace should start automatically performing runs immediately after creation. | `false` | |
| speculative_enabled | Whether the workspace allows speculative plans. | `false` | |
| ssh_key_id | SSH key ID to assign the workspace. | `false` | |
| file_triggers_enabled | Whether to filter runs based on the changed files in a VCS push. | `false` | |
| remote_states | YAML encoded remote state blocks to configure in the workspace. | `false` | |
| team_access | YAML encoded teams and their associated permissions to be granted to the created workspaces. | `false` | |
| allow_workspace_deletion | Whether to allow workspaces to be deleted. If enabled, workspace state may be irrecoverably deleted. | `false` | false |
| run_triggers | YAML encoded list of either workspace IDs or names that, when applied, trigger runs in all the created workspaces (max 20) | `false` | |
| workspace_run_triggers | A YAML encoded map of workspaces to workspace IDs or names, which like `run_triggers`, will trigger a run for the associated workspace when the source workspace is ran | `false` | |
| notification_configuration | A YAML encoded map of notification settings applied to all created workspaces | `false` | |
### Backend Config
This project supports any backend supported by the selected Terraform version. The backend is used to persist the state of the Terraform Cloud workspace itself and its related resources (e.g., variables, teams). You generally should not pass "remote" workspace configuration, since that creates a circular dependency.
If no backend is passed, the default Terraform local backend will be used.
**NOTE** When using the default local backend, `import` should always be `true` to ensure that resources can be managed across action runs.
```yml
with:
...
backend_config: |-
s3:
bucket: my-bucket
key: foo.tfstate
region: us-east-1
role_arn: arn:aws:iam::123456789:role/terraform
access_key: xxx
secret_key: xxx
```
### Variables and Workspace Variables
`variables` are applied to all created workspaces, where `workspace_variables` are applied to the noted workspace. Per the [workspace docs](https://www.terraform.io/docs/cloud/workspaces/variables.html), `category` field must be set to either `env` or `terraform`.
```yml
...
with:
workspaces: |-
- staging
- production
variables: |-
- key: general-secret
value: "${{ secrets.SECRET }}"
category: env
sensitive: true
workspace_variables: |-
staging:
- key: environment
value: staging
category: terraform
production:
- key: environment
value: production
category: terraform
```
#### Remote state variable reference
Remote states can be configured and referenced for the variable `value` field
```yml
...
with:
variables: |-
- key: s3_secret
value: ${data.terraform_remote_state.workspace_s3.outputs.secret}
category: env
- key: tf_cloud_secret
value: ${data.terraform_remote_state.workspace_tf_cloud.outputs.secret}
category: env
remote_states: |-
workspace_s3:
backend: remote
config:
bucket: s3-bucket
key: terraform.tfstate
region: us-east-1
workspace_tf_cloud:
backend: remote
config:
hostname: app.terraform.io
organization: organization
workspaces:
name: workspace-tf-cloud
```
### Team access
Create or update existing team access resources. Team `id` and `name` cannot both be simultaneously set.
```yml
with:
team_access: |-
- name: Readers
access: read
- name: Writers
permissions:
runs: apply
variables: write
state_versions: write
sentinel_mocks: read
workspace_locking: true
```
### Importing existing resources
By default, the action will import any existing resources it can find based on a unique attribute. It makes multiple passes to discover all existing resources, first finding matching workspaces and then related resources (variables, team access).
When `apply` is set to `false`, the configured backend state will be copied to a local backend and `import` will be set to `true`. This grants some visibility into the import changes before they are actually applied to the configured backend.
To disable the import feature, set `import` to `false`
```yml
...
with:
import: false
```
### Workspace tags
Workspace tags can be specified in two ways, `tags` and `workspace_tags`. `tags` apply to every workspace, while `workspace_tags` apply to the specified workspace only
```yml
tags: |-
- all
workspace_tags: |-
staging:
- staging
production:
- production
```
### Run Triggers
The following configuration will add a run trigger for the `alpha` and `beta` workspaces when workspace `parent-workspace` is ran, and will also add two more triggers to the `alpha` workspace when either workspace `ws-abc123` or `ws-def456` are ran
```yml
workspaces: |-
- alpha
- beta
run_triggers: |-
- name: parent-workspace
workspace_run_triggers: |-
alpha:
- id: ws-abc123
- id: ws-def456
```
### Notification configuration
The following configuration will add a [notification configuration](https://registry.terraform.io/providers/hashicorp/tfe/latest/docs/resources/notification_configuration#destination_type) for each workspace.
```yml
workspaces: |-
- alpha
- beta
notification_configuration: |-
name: my-notification
destination_type: email
email_addresses:
- [email protected]
enabled: true
```
## Outputs
## Outputs
| parameter | description |
| - | - |
| plan | A human friendly output of the Terraform plan. |
| plan_json | A JSON representation of the Terraform plan. |
## Development
### Test
To test the project
`go test -v -short ./...`
### Documentation
Documentation is generated from `action.yml` using [action-docs](https://github.com/npalm/action-docs). To generate documentation and update it in place:
```sh
make docs
```
On each pull request, a workflow will automatically update the documentation and fail if the documentation is out of date.
### Lint
This project uses [`golangci-lint`](https://github.com/golangci/golangci-lint)
To lint the project
`golangci-lint run ./...`
To auto fix issues where supported
`golangci-lint run --fix ./...`