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:

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

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

javascript
// @ts-check
/// <reference types="@actions/github-script" />

const { getMessages, renderTemplate, toSnakeCase } = require("./messages_core.cjs");

/**
 * @typedef {Object} MyNewMessageContext
 * @property {string} placeholder1 - Description of placeholder1
 * @property {string} placeholder2 - Description of placeholder2
 */

function getMyNewMessage(ctx) {
	const messages = getMessages();
	const templateContext = toSnakeCase(ctx);
	const defaultMessage = "Default message with {placeholder1} and {placeholder2}";

	return messages?.myNewMessage
		? renderTemplate(messages.myNewMessage, templateContext)
		: renderTemplate(defaultMessage, templateContext);
}

module.exports = {
	getMyNewMessage,
};

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:

javascript
import { describe, it, expect, beforeEach, vi } from "vitest";

const mockCore = { warning: vi.fn() };
global.core = mockCore;

describe("getMyNewMessage", () => {
	beforeEach(() => {
		vi.clearAllMocks();
		delete process.env.GH_AW_SAFE_OUTPUT_MESSAGES;
	});

	it("returns the default message when no custom template is configured", async () => {
		const { getMyNewMessage } = await import("./messages_my_new.cjs");
		const result = getMyNewMessage({ placeholder1: "value1", placeholder2: "value2" });
		expect(result).toBe("Default message with value1 and value2");
	});

	it("uses the custom template when configured", async () => {
		process.env.GH_AW_SAFE_OUTPUT_MESSAGES = JSON.stringify({ myNewMessage: "Custom: {placeholder1}" });
		const { getMyNewMessage } = await import("./messages_my_new.cjs");
		const result = getMyNewMessage({ placeholder1: "test", placeholder2: "ignored" });
		expect(result).toContain("Custom: test");
	});
});

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

javascript
const { getMyNewMessage } = require("./messages_my_new.cjs");

const message = getMyNewMessage({
	placeholder1: actualValue1,
	placeholder2: actualValue2,
});

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:

markdown
| Module | Purpose | Exported Functions |
|--------|---------|-------------------|
| `messages_my_new.cjs` | My new message description | `getMyNewMessage` |

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/.