name: messages description: Instructions for adding new message types to the safe-output messages system

Adding New Message Types Guide

This guide explains how to add a new message type to the GitHub Agentic Workflows safe-output messages system. Follow these steps to ensure the new message is available in frontmatter, parsed by the compiler, available in JavaScript, and properly bundled.

Overview

The messages system allows workflow authors to customize messages displayed in safe-output operations. Messages flow through:

Frontmatter (YAML) → 2. JSON Schema → 3. Go Compiler → 4. JavaScript Modules → 5. Bundler

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 (e.g., my-new-message)
Document all available placeholders in the description
Provide helpful examples
Run make build after changes (schema is embedded in binary)

Step 2: Update Go Struct

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

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

Key points:

Use CamelCase for Go field name
Use kebab-case for YAML tag (matches frontmatter)
Use camelCase for JSON tag (used in JavaScript)
Add omitempty to both tags

Step 3: Update Go Parser

If needed, update the parser in pkg/workflow/safe_outputs.go:

func parseMessagesConfig(messagesMap map[string]any) *SafeOutputMessagesConfig {
	config := &SafeOutputMessagesConfig{}
	// ... existing parsing ...
	
	if myNewMessage, ok := messagesMap["my-new-message"].(string); ok {
		config.MyNewMessage = myNewMessage
	}
	
	return config
}

Note: The parser uses reflection for most fields, so this step may not be needed for simple string fields.

Step 4: Create JavaScript Message Module

Create a new file pkg/workflow/js/messages_my_new.cjs:

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

/**
 * My New Message Module
 *
 * This module provides the my-new-message generation
 * for [describe when it's used].
 */

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

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

/**
 * Get the my-new-message, using custom template if configured.
 * @param {MyNewMessageContext} ctx - Context for message generation
 * @returns {string} The generated message
 */
function getMyNewMessage(ctx) {
  const messages = getMessages();

  // Create context with both camelCase and snake_case keys
  const templateContext = toSnakeCase(ctx);

  // Default message template
  const defaultMessage = "Default message with {placeholder1} and {placeholder2}";

  // Use custom message if configured
  return messages?.myNewMessage
    ? renderTemplate(messages.myNewMessage, templateContext)
    : renderTemplate(defaultMessage, templateContext);
}

module.exports = {
  getMyNewMessage,
};

Key points:

File naming: messages_<category>.cjs (flat structure, not subfolder)
Import from ./messages_core.cjs for shared utilities
Use JSDoc for type definitions
Provide sensible default message
Support both custom and default templates

Step 5: Add Tests

Create pkg/workflow/js/messages_my_new.test.cjs:

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

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

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

  it("should return default message when no custom message 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("should use custom message 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 tests with make test-js.

Step 6: Update Core Module TypeDef

Add the new property to the SafeOutputMessages typedef in pkg/workflow/js/messages_core.cjs:

/**
 * @typedef {Object} SafeOutputMessages
 * @property {string} [footer] - Custom footer message template
 * // ... existing properties ...
 * @property {string} [myNewMessage] - Custom my-new-message template
 */

Also update the getMessages() function return object:

return {
  footer: rawMessages.footer,
  // ... existing fields ...
  myNewMessage: rawMessages.myNewMessage,
};

Step 7: Update Barrel File

Add the re-export to pkg/workflow/js/messages.cjs:

// Re-export my new messages
const { getMyNewMessage } = require("./messages_my_new.cjs");

module.exports = {
  // ... existing exports ...
  getMyNewMessage,
};

Step 8: Register in Go Embeddings

Add to pkg/workflow/js.go:

//go:embed js/messages_my_new.cjs
var messagesMyNewScript string

Add to GetJavaScriptSources():

func GetJavaScriptSources() map[string]string {
	return map[string]string{
		// ... existing entries ...
		"messages_my_new.cjs": messagesMyNewScript,
	}
}

Step 9: Use in Consumer Scripts

Import directly from the specific module in scripts that need it:

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

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

Step 10: Update Documentation

Update specs/safe-output-messages.md:

Add the new message to the "Message Categories" section
Document placeholders and usage
Add examples

Update the Message Module Architecture table:

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

Verification Checklist

Before committing:

File Summary

File	Purpose	Changes Needed
`pkg/parser/schemas/main_workflow_schema.json`	JSON Schema	Add field definition
`pkg/workflow/compiler.go`	Go struct	Add struct field
`pkg/workflow/safe_outputs.go`	Parser	Add parsing logic (if needed)
`pkg/workflow/js/messages_my_new.cjs`	JavaScript module	Create new file
`pkg/workflow/js/messages_my_new.test.cjs`	Tests	Create new file
`pkg/workflow/js/messages_core.cjs`	Core utilities	Update typedef
`pkg/workflow/js/messages.cjs`	Barrel file	Add re-export
`pkg/workflow/js.go`	Go embeddings	Add embed directive
`specs/safe-output-messages.md`	Documentation	Document new message

Example: Adding `close-older-discussion` Message

This message type was added following this process:

Schema: Added close-older-discussion field with placeholders {new_discussion_number}, {new_discussion_url}, {workflow_name}, {run_url}
Go struct: Added CloseOlderDiscussion string field
JavaScript: Created messages_close_discussion.cjs with getCloseOlderDiscussionMessage()
Tests: Added corresponding test file
Bundler: Registered in GetJavaScriptSources()
Consumer: Used in close_older_discussions.cjs via direct import

See these files for a working implementation example.

messages

Installation

Details

Usage

Skill Instructions

name: messages description: Instructions for adding new message types to the safe-output messages system

Adding New Message Types Guide

Overview

Step 1: Update JSON Schema

Step 2: Update Go Struct

Step 3: Update Go Parser

Step 4: Create JavaScript Message Module

Step 5: Add Tests

Step 6: Update Core Module TypeDef

Step 7: Update Barrel File

Step 8: Register in Go Embeddings

Step 9: Use in Consumer Scripts

Step 10: Update Documentation

Verification Checklist

File Summary

Example: Adding `close-older-discussion` Message

More by githubnext

messages

Installation

Details

Usage

Skill Instructions

name: messages description: Instructions for adding new message types to the safe-output messages system

Adding New Message Types Guide

Overview

Step 1: Update JSON Schema

Step 2: Update Go Struct

Step 3: Update Go Parser

Step 4: Create JavaScript Message Module

Step 5: Add Tests

Step 6: Update Core Module TypeDef

Step 7: Update Barrel File

Step 8: Register in Go Embeddings

Step 9: Use in Consumer Scripts

Step 10: Update Documentation

Verification Checklist

File Summary

Example: Adding close-older-discussion Message

More by githubnext

Example: Adding `close-older-discussion` Message