YAML templates

Use a YAML action template to compose existing actions into a reusable action.

Template shape

Create a .yml file in your registry templates directory. Define inputs in expects, run actions in steps, and return the final value from returns.

type: action
definition:
  title: Post message
  description: Post a message to a Slack channel.
  display_group: Slack
  namespace: tools.slack
  name: post_message
  expects:
    channel:
      type: str
      description: The Slack channel ID.
    text:
      type: str
      description: The message text.
  steps:
    - ref: post_message
      action: tools.slack_sdk.call_method
      args:
        sdk_method: chat_postMessage
        params:
          channel: ${{ inputs.channel }}
          text: ${{ inputs.text }}
  returns: ${{ steps.post_message.result }}

Start every file with type: action.
Use tools.<integration> for the namespace.
Set title, description, display_group, namespace, and name in definition.
Define inputs in expects.
Build the action in steps.
Return the final value from returns.

Expressions

Use ${{ }} for expressions. Use inputs to read the inputs you defined in expects. Use steps to read the result of an earlier step. After a step runs, its output is available at steps.<ref>.result.

Read an input

args:
  channel: ${{ inputs.channel }}
  text: ${{ inputs.text }}

Read an earlier step result

returns: ${{ steps.post_message.result }}

Build one step from another

steps:
  - ref: lookup_user
    action: tools.slack.users.lookup_user_by_email
    args:
      email: ${{ inputs.email }}
  - ref: post_message
    action: tools.slack.chat.post_message
    args:
      channel: ${{ steps.lookup_user.result.id }}
      text: Hello

You can use:

inputs
steps
SECRETS
VARS
FN.*

Secrets

Declare what each template needs under definition.secrets (API keys, structured types, or OAuth). That list drives which credentials must exist for the action when the workflow runs. Use the same ${{ SECRETS... }} paths in args as in any other expression. Use the same ${{ SECRETS... }} syntax as workflow actions. Custom secrets (API keys, SSH, mTLS, CA bundles, and so on):

${{ SECRETS.<secret_name>.<KEY> }}

OAuth

OAuth expressions use the provider’s exact ID, not its display name.

Built-in providers use stable lowercase IDs assigned by Tracecat, with underscores between words, such as slack, google_drive, and microsoft_sentinel.
Custom providers use an ID derived from the provider name, or from the requested ID when you create one through the API. Tracecat slugifies it with underscores and prepends custom_. My Security API becomes custom_my_security_api. If that ID is already used for the same grant type, Tracecat appends _1, _2, and so on.

Append _oauth to the exact provider ID for the secret name. For the key, uppercase the complete provider ID, preserve its underscores and any numeric suffix, then append _USER_TOKEN for authorization_code or _SERVICE_TOKEN for client_credentials.

# authorization_code grant
${{ SECRETS.<provider_id>_oauth.<PROVIDER_ID_UPPER>_USER_TOKEN }}

# client_credentials grant
${{ SECRETS.<provider_id>_oauth.<PROVIDER_ID_UPPER>_SERVICE_TOKEN }}

A built-in google_drive authorization-code provider and a custom custom_my_security_api client-credentials provider resolve as:

${{ SECRETS.google_drive_oauth.GOOGLE_DRIVE_USER_TOKEN }}
${{ SECRETS.custom_my_security_api_oauth.CUSTOM_MY_SECURITY_API_SERVICE_TOKEN }}

When either grant type is allowed, use a fallback:

${{ SECRETS.microsoft_sentinel_oauth.MICROSOFT_SENTINEL_USER_TOKEN || SECRETS.microsoft_sentinel_oauth.MICROSOFT_SENTINEL_SERVICE_TOKEN }}

Tracecat refreshes expiring authorization-code tokens when the provider issued a refresh token, and reacquires client-credentials tokens with the stored client credentials. The expression resolves only to the current access-token string, which may be a JWT or an opaque token, not the refresh token.

Python UDFs

Declare credentials in @registry.register(..., secrets=[...]).

RegistrySecret: static keys; set secret_type to ssh_key, mtls, or ca_cert when needed (secret types). Optional: optional, optional_keys.
RegistryOAuthSecret: declares a dependency on an existing OAuth integration. Pass the provider_id and grant_type that match the integration in your workspace (a mismatch — for example declaring authorization_code when the integration uses client_credentials — will not resolve).

Read values with secrets.get("<KEY>") (key only, e.g. GOOGLE_DRIVE_USER_TOKEN), not a SECRETS. path.

from tracecat_registry import RegistryOAuthSecret, RegistrySecret, registry, secrets

api = RegistrySecret(name="exa", keys=["EXA_API_KEY"])

oauth = RegistryOAuthSecret(
    provider_id="google_drive",
    grant_type="authorization_code",
)

YAML

Under definition, set a secrets list (same validator as Python). Custom (optional secret_type for structured secrets):

definition:
  secrets:
    - name: exa
      keys: ["EXA_API_KEY"]
    - name: ansible
      keys: ["PRIVATE_KEY"]
      secret_type: ssh_key

OAuth:

definition:
  secrets:
    - type: oauth
      provider_id: microsoft_teams
      grant_type: authorization_code

The provider_id and grant_type must match an integration already configured in your workspace. Use ${{ SECRETS.<provider_id>_oauth.<TOKEN_KEY> }} in args. Set optional: true on an OAuth entry when it is not always required.

Example providers

See integrations/google_drive.py and integrations/slack_sdk.py for UDFs that use OAuth credentials. See tracecat_registry/core/ssh.py for an ssh_key secret example. For YAML templates, see microsoft_teams/send_message.yml (authorization_code), google_docs/create_document.yml (client_credentials), and microsoft_sentinel/.../get_alert_rule_template.yml (optional dual grant). See templates/tools/exa/search.yml for a simple API key template. For the full list of built-in provider IDs, see tracecat/integrations/providers/__init__.py.

Limitations

Template steps only support ref, action, and args.
Template steps run in order.
Template steps do not support run_if, for_each, join_strategy, start_delay, timeout, or max_attempts.
Templates can call tools actions, other templates, and core.script.run_python. Other platform actions are not supported inside templates.
If a later step fails, you do not get a final result with earlier step outputs. Keep templates short. In practice, do not build templates with more than 2 steps.

Example templates

All integrations in Tracecat are open source. Browse template actions for more examples. For concrete examples, browse the Slack templates and CrowdStrike templates.

Overview

Building automations

Building agents

Building custom actions

Self-hosting

Authentication

Security

Template shape

Expressions

Secrets

OAuth

Python UDFs

YAML

Example providers

Limitations

Example templates

​Template shape

​Expressions

​Secrets

​OAuth

​Python UDFs

​YAML

​Example providers

​Limitations

​Example templates

Template shape

Expressions

Secrets

OAuth

Python UDFs

YAML

Example providers

Limitations

Example templates