Documentation Grafana Cloud Platform Workflows Manage as code

Manage workflows as code

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.

If you haven’t managed Grafana as code before, start with Build workflows with an AI agent.

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

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. For the available steps, refer to Step and trigger types 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

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.

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.

• Build workflows with an AI agent
  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
  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
  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
  Manage Grafana Workflows with the Grafana Terraform provider's generic app platform resource, including folders, variables, imports, and changes made outside Terraform.