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": 

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/compiler.go:

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: Update the parser if needed

If the message needs custom parsing logic, update the workflow parser in pkg/workflow/safe_outputs.go or the relevant config block. Most simple string fields will be wired automatically by the existing reflection-based parser.

Step 4: Create the JavaScript message module

Create the new module in the current shared JS location, typically pkg/workflow/js/:

Key points:

• File naming: messages_<category>.cjs
• Reuse ./messages_core.cjs for shared helpers
• Use JSDoc for types and default behavior
• Keep the default message sensible and deterministic

Step 5: Add tests

Create a matching test file, for example pkg/workflow/js/messages_my_new.test.cjs:

Run the relevant tests with make test-js or the targeted Vitest file.

Step 6: Update the core JS type metadata and exports

Update the SafeOutputMessages typedef and the return object in pkg/workflow/js/messages_core.cjs, and re-export the message helper from pkg/workflow/js/messages.cjs.

Step 7: Wire it into the real build path

Do not add any new //go:embed entries to pkg/workflow/js.go for a normal message module. The current system packages JavaScript through the action-generation/build path.

Instead:

• keep the JS module in pkg/workflow/js/ or the relevant action folder,
• update the action dependency map or action source if needed,
• rebuild the action bundle with make actions-build.

Step 8: Use the message in consumer scripts

Step 9: Update documentation

Document the new message in the repo’s relevant safe-output docs, and keep the examples aligned with the current action-based JavaScript build flow.

Verification Checklist

Before committing a message change:

• Frontmatter and schema updated
• Go config/struct updated if needed
• JS module created under the correct source tree
• Tests added and passing
• messages_core.cjs and messages.cjs updated if relevant
• Generated action/build output refreshed when required
• No stale embedding instructions are introduced for the current action-based JS build flow

References

• actions/README.md - current action-generation/build workflow
• pkg/workflow/js/messages_core.cjs - shared safe-output message helpers
• pkg/workflow/js/messages.cjs - message exports
• pkg/parser/schemas/main_workflow_schema.json - schema source of truth

Update the Message Module Architecture table:

Notes

For current gh-aw work, keep message modules aligned with the action-generation flow instead of the historical Go-embed pattern. If you need an example, review the existing safe-output modules under pkg/workflow/js/ and the generated action files under actions/.