messages

Adding New Message Types Guide

Use this guide to add a new safe-output message type so it works in the current gh-aw pipeline: frontmatter → schema → Go compiler → JavaScript modules → action/workflow build output.

Overview

The messages system lets workflow authors customize safe-output messages. The current architecture does not rely on the old pkg/workflow/js.go embedding registry for runtime shipping.

Current flow:

1. Frontmatter (YAML)
2. JSON Schema
3. Go Compiler
4. JavaScript module under pkg/workflow/js/ or actions/setup/js/
5. Action/workflow bundle generation via make actions-build or the relevant workflow build path

Step 1: Update JSON Schema

Add the new message field to pkg/parser/schemas/main_workflow_schema.json in the messages object:

{
	"messages": {
		"properties": {
		  "my-new-message": {
		    "type": "string",
		    "description": "Description of when this message is used. Available placeholders: {placeholder1}, {placeholder2}.",
		    "examples": [
		      "Example message with {placeholder1}"
		    ]
		  }
		}
	}
}

Key points:

• Use kebab-case for the YAML field name (for example my-new-message)
• Document placeholders in the description
• Provide helpful examples
• Rebuild the schema-backed binary or run the relevant compile checks after changes

Step 2: Update Go Struct

Add the field to SafeOutputMessagesConfig in pkg/workflow/safe_outputs_config_types.go:

type SafeOutputMessagesConfig struct {
	// ... existing fields ...
	MyNewMessage string `yaml:"my-new-message,omitempty" json:"myNewMessage,omitempty"`
}

Key points:

• Use CamelCase for Go field names
• Use kebab-case for YAML tags
• Use camelCase for JSON tags
• Add omitempty to both tags

Step 3: Wire the field in the parser

Add the field to parseMessagesConfig in pkg/workflow/safe_outputs_messages_config.go. Each field is mapped explicitly; simple string fields use extractStringFromMap: