---
title: "Manage workflows as code | Grafana Cloud documentation"
description: "Create, update, run, and inspect Grafana Workflows from files, scripts, Terraform, or an AI agent instead of the Workflows app."
---

> For a curated documentation index, see [llms.txt](/llms.txt). For the complete documentation index, see [llms-full.txt](/llms-full.txt).

# Manage workflows as code

> Note
> 
> Grafana Workflows is currently in [public preview](/docs/release-life-cycle/). Grafana Labs offers limited support, and breaking changes might occur prior to the feature being made generally available.

You can build and change Grafana Workflows without opening the Workflows app. Keep your workflows as files, and use a tool to send them to Grafana.

Managing workflows this way lets you:

- Keep every workflow in version control, such as Git, so you can see who changed what and roll back a mistake.
- Review changes in a pull request before they reach production.
- Copy the same workflows to more than one Grafana Cloud stack.
- Describe a workflow in plain language and let an AI agent build and test it for you.

## Choose a tool

Workflows supports several tools. They all work with the same workflow files, so a file you write for one tool works with the others.

Expand table

| Tool                                                                                             | Best for                                                        | You should be comfortable with                   |
|--------------------------------------------------------------------------------------------------|-----------------------------------------------------------------|--------------------------------------------------|
| [Build workflows with an AI agent](/docs/grafana-cloud/platform/workflows/as-code/build-with-ai) | Building a workflow from a plain-language description           | Running commands in a terminal                   |
| [Use gcx](/docs/grafana-cloud/platform/workflows/as-code/use-gcx)                                | Pulling workflows to files, editing them, and pushing them back | Running commands in a terminal, and reading YAML |
| [Use the API](/docs/grafana-cloud/platform/workflows/as-code/use-the-api)                        | Scripts, CI jobs, and integrations with other systems           | The command line, JSON, and HTTP requests        |
| [Use Terraform](/docs/grafana-cloud/platform/workflows/as-code/use-terraform)                    | Teams that already manage Grafana with Terraform                | Terraform                                        |

If you haven’t managed Grafana as code before, start with [Build workflows with an AI agent](/docs/grafana-cloud/platform/workflows/as-code/build-with-ai).

Terraform creates, updates, and deletes workflows, but it doesn’t run them. To run a workflow and read its results, use gcx or the API.

## Learn the key terms

The pages in this section use the following terms:

*Workflow definition*

The file that describes a workflow: its name, its trigger, and its steps. The Workflows app stores every workflow as a definition.

*Folder UID*

The unique ID of a Grafana folder. Every workflow belongs to a folder, and the folder controls who can view and edit it. To find a folder UID, open the folder in Grafana and copy the UID from the URL, which has the form `/dashboards/f/<FOLDER_UID>/`.

*Service account token*

A token that tools use to sign in to Grafana instead of your own account.

*Namespace*

The ID that Grafana uses for your stack, in the form `stacks-<STACK_ID>`. gcx and Terraform fill it in for you. You only need it when you call the API directly.

## Understand the workflow definition

A workflow definition is a YAML or JSON file with the same shape in every tool:

YAML ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```yaml
apiVersion: workflows.ext.grafana.app/v1alpha1
kind: Definition
metadata:
  name: <WORKFLOW_NAME>
  annotations:
    grafana.app/folder: <FOLDER_UID>
spec:
  name: <DISPLAY_NAME>
  enabled: true
  startWhen:
    matchingRules: []
    schedules: []
  steps: []
```

The fields work as follows:

- `apiVersion` and `kind` tell Grafana that the file is a workflow. Copy them as shown.
- `metadata.name` is the workflow’s ID. Use lowercase letters, numbers, and hyphens. Tools use this ID to find the workflow.
- `metadata.annotations` holds the `grafana.app/folder` annotation, which names the folder by its UID. Workflows requires it.
- `spec.name` is the display name that the Workflows app shows.
- `spec.enabled` turns the workflow on or off.
- `spec.startWhen` sets the triggers. Include both `matchingRules` and `schedules`. Leave both empty for a workflow that runs only when you start it.
- `spec.steps` lists the steps the workflow runs.

For every field, refer to [Understand the definition structure](/docs/grafana-cloud/platform/workflows/create-workflows/#understand-the-definition-structure). For the available steps, refer to [Step and trigger types reference](/docs/grafana-cloud/platform/workflows/reference).

## Understand validation

Workflows checks every definition when you save it, no matter which tool sends it. The check confirms, for example, that each step type exists, that required step inputs have values, and that the definition names a folder. If something is wrong, Workflows rejects the definition and names each problem, for example:

console ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```console
step "a" has unknown type "not.a.step"; step "b" is missing required field "template" for type "transform"
```

Workflows checks required step inputs only when `enabled` is `true`. That lets you save an unfinished draft with `enabled: false`. Before Workflows runs any workflow, including a draft you test, it runs the full check.

## Give tools access

A tool signs in with a service account token. The service account needs the same access a person needs to edit workflows:

- The Editor basic role.
- Edit access to the folder that holds the workflow.
- The Events Reader role, to read run results. The Editor basic role includes it.

For details, refer to [Manage access](/docs/grafana-cloud/platform/workflows/manage-access).

## Avoid conflicting edits

The Workflows app doesn’t show which tool manages a workflow, and it doesn’t stop people from editing it. If someone changes a workflow in the editor, your tool overwrites that change the next time it sends its copy.

To avoid lost changes, manage each workflow from one place:

- Put code-managed workflows in their own folder.
- Give most people view access to that folder, and give edit access only to the people and service accounts that maintain it.

<!--THE END-->

- [Build workflows with an AI agent](/docs/grafana-cloud/platform/workflows/as-code/build-with-ai/)  
  Describe a workflow in plain language and let an AI coding agent build, validate, and test it for you with the gcx CLI.
- [Use gcx](/docs/grafana-cloud/platform/workflows/as-code/use-gcx/)  
  Use the gcx command-line tool to pull, edit, validate, push, and run Grafana Workflows, and read the results of workflow runs.
- [Use the API](/docs/grafana-cloud/platform/workflows/as-code/use-the-api/)  
  Create, update, delete, run, and inspect Grafana Workflows over HTTP with a service account token, including how to read step outputs from workflow runs.
- [Use Terraform](/docs/grafana-cloud/platform/workflows/as-code/use-terraform/)  
  Manage Grafana Workflows with the Grafana Terraform provider's generic app platform resource, including folders, variables, imports, and changes made outside Terraform.