Workflow management tools

Overview

These write tools change your workflows' definitions. To run a workflow, see create_workflow_run. For what each workflow setting means, see Workflow components.

All four are write tools, see Availability.

tip

The sg-create-workflow, sg-update-workflow and sg-upgrade-workflow agent skills (or create-workflow, update-workflow and upgrade-workflow when installed from StackGuardian/skills) guide your assistant through these tools step by step. The assistant offers you real choices, such as groups, connectors and templates, and summarizes the change for you to confirm before anything is created.

create_workflow

Creates a new workflow in one of your workflow groups, from either:

• a library template: a pinned template revision plus its input values, or
• a git repository: the repository URL, branch or tag, working directory, and, for private repositories, a VCS connector or a vault secret holding a token. Generic git hosts accept a vault secret only.

What you can set

Setting	Description
Workflow group (required)	The group to create the workflow in. It must already exist, unless you explicitly ask for a new group to be created.
Name (required)	1–100 characters.
Source (required)	A template or a git repository, see above.
Workflow type	Terraform (the default), OpenTofu or Custom. Custom workflows run a pipeline of up to 10 steps instead of Terraform. The type can't be changed later.
Description, tags, context tags	Up to 10 tags.
Cloud connector	The connector the workflow deploys through. Leave it out if the workflow doesn't touch cloud infrastructure.
Environment variables	Up to 20, as plain values or references to vault secrets.
Terraform settings	Terraform version, managed state, drift checks and their schedule, plan and init options, lifecycle hooks and more.
Approvals	Users or SSO groups who can approve a paused run, and how many approvals are needed. 0 means every listed approver must approve. Approvers alone don't make runs pause: for Terraform and OpenTofu workflows also turn on the pre-apply approval Terraform setting, and for Custom workflows set approval on the step.
Runner	StackGuardian's shared runners (the default), or one of your private runner groups.
Post-run actions	Chain another workflow or stack, or send email or webhook notifications, depending on how the run ends.
Schedules	Up to 10 cron schedules for automatic runs.
Caching	Keep directories such as .terraform between runs to speed them up.
CPU and memory	The run container's size.
Parallel runs	Custom workflows only: let several runs execute at the same time.

Checks before the workflow is created

• The workflow group, cloud connector, VCS connector and secrets are checked against your organization. If one doesn't exist, the response lists the valid options for the assistant to offer you. Runner group names and template ids are validated by the platform when the workflow is created.
• A Custom workflow must end up with steps, from the request or from its template. Otherwise every run would fail, so the tool refuses to create it.
• Creating a workflow from a draft (unpublished) template revision is allowed, and the response includes a warning.

The response includes the created workflow and, where available, a link to it in the dashboard.

Example prompts

"Create a workflow called staging-vpc in the networking group from our aws-vpc template, using the aws-staging connector."

"Create a Terraform workflow from github.com/acme/infra, branch main, folder envs/dev, with drift checks every night."

update_workflow

Changes an existing workflow. Pass only what you want to change. Settings you don't name are kept, apart from the cases listed below. It works in three modes.

1. Change settings

Change any of the settings listed under create_workflow, the template input values, or the source itself. The tool reads the current workflow first and merges your change in where it can:

• A partial change, such as turning on drift checks, keeps the other Terraform settings.
• Environment variables are added or replaced by name. Variables you don't mention are kept.
• Post-run actions are merged by type and outcome. For example, adding completion notifications keeps your existing chaining. Within one type and outcome, though, the list is replaced, see below.
• Context tags are merged. Setting a key to null removes it.

A few settings replace the stored value instead of merging, so your assistant has to send the complete set:

• Tags
• Template input values
• Terraform lifecycle hook lists, one list per lifecycle point
• Post-run action lists for a given outcome, such as the webhooks sent on completion. Adding a webhook means sending the existing ones too.
• Custom workflow steps
• Schedules
• Caching
• Approvals
• Runner
• GitHub pull request triggers

Changing the source replaces the whole source configuration. Template input values, working directory and git authentication that aren't sent again are dropped, so include everything you want to keep.

You can also activate or deactivate a workflow. Workflows inside a stack are activated or deactivated through the stack instead.

2. Upgrade to a new template revision

Move a template-based workflow to another revision of its template. Choose how your customizations are handled:

• Preserve settings keeps your workflow's customizations.
• Reset to template takes the new revision's defaults. This includes schedules, which usually clears them, since templates rarely define any. Include the schedules you want to keep with the upgrade.

Either kind of upgrade resets CPU and memory to the template's values. Include your sizing with the upgrade to keep it.

Environment variables sent with an upgrade replace the workflow's whole list instead of being added by name. Send every variable you want to keep, including secret references, or leave environment variables out of the upgrade.

3. Preview an upgrade

A dry run of an upgrade changes nothing. It shows what the upgrade would add, modify and remove across input values, environment variables, connectors and custom step parameters. Your assistant can show you the preview, then apply the upgrade once you agree.

Good to know

• The workflow's name and type can't be changed.
• The platform refuses a runner change while the workflow has active runs. Cancel them first.

Example prompts

"Turn on drift detection for payments-api and add the environment variable LOG_LEVEL=debug."

"Upgrade staging-vpc to revision 5 of its template. Show me what changes first."

"Make payments-api pause for approval from platform-team before it applies."

delete_workflow

Deletes a workflow's records: the workflow itself, its runs, schedules, artifacts and its stored Terraform state.

This does not destroy infrastructure

Every resource the workflow created keeps running, and keeps costing money. The Terraform state that could have torn it down cleanly is deleted with the workflow.

If the infrastructure should go too, destroy it first. Run the workflow with the destroy action, wait for the run to complete, then delete the workflow.

Your assistant must confirm the deletion with you, name the workflow, and ask whether its infrastructure has been destroyed. The tool only deletes once you confirm.

Good to know

• A workflow with a run still in progress (queued, running or waiting for approval) can't be deleted. Cancel or finish the run first.
• The tool warns you when a Terraform or OpenTofu workflow still looks like it has live infrastructure.
• If the workflow doesn't exist, the response says nothing was deleted.

Example prompts

"Destroy and then delete the demo-sandbox workflow."

"Delete the old-test workflow. Its infrastructure is already gone."

upload_workflow_tfstate_url

Replaces a workflow's Terraform state with a state file from your computer, for example when migrating an existing Terraform project into StackGuardian.

The tool doesn't upload anything itself. It returns a link valid for 5 minutes and a ready-to-run curl command. You run the command yourself, so the state file never passes through the assistant.

warning

The next run acts on whatever state you upload. A wrong file can make Terraform destroy or recreate live infrastructure. For workflows inside a stack, the previous state can't be restored.

Input	Description
Workflow (required)	As found with search_workflows.
File path (required)	Where the state file is on your computer. It's only used to fill in the curl command.
Confirmation (required)	Your explicit go-ahead to overwrite the state.

Good to know

• Your assistant should ask you for the file path, and must never open or read the file. A Terraform state file holds every resource attribute in plain text, including passwords, private keys and tokens.
• Only Terraform and OpenTofu workflows with StackGuardian-managed state are supported.
• Workflows whose state is stored in Azure Blob storage on a private runner aren't supported. The tool refuses to hand out a link, because the platform's Azure link grants more access than an upload needs. Upload the state another way, or ask the platform team.
• The tool refuses while the workflow's state is locked by a run in progress.
• The response tells you whether state already exists and whether an overwrite can be rolled back.

Example prompts

"I'm migrating an existing project into the legacy-app workflow. Help me upload my terraform.tfstate."