Token Diff PR Comment Workflow

This document describes the GitHub Action workflow that automatically generates and posts token change reports as comments on pull requests.

Overview

The token-diff-pr-comment.yml workflow automatically:

1. Triggers on pull request events (opened, synchronized, reopened)
2. Analyzes token changes between the base branch and PR branch
3. Posts or updates a comment on the PR with the diff report
4. Handles cases with no changes and error scenarios

Workflow Details

Trigger Conditions

The workflow runs when:

• A pull request is opened, synchronized (updated), or reopened
• Changes are made to token-related files:
  • packages/tokens/src/**
  • packages/tokens/schemas/**

Environment Setup

• Toolchain: Uses moonrepo/setup-toolchain@v0 for automatic Node.js and pnpm setup
• Versions: Automatically determined from project configuration (moon.yml/package.json)
• Runner: ubuntu-latest

Permissions Required

• contents: read - To checkout the repository
• pull-requests: write - To create and update PR comments

Process Flow

1. Repository Checkout: Fetches the full git history with fetch-depth: 0
2. Toolchain Setup: Uses moonrepo to automatically configure Node.js and pnpm
3. Dependencies: Installs diff-generator dependencies using pnpm
4. Diff Generation:
   • Compares base branch vs head branch
   • Outputs markdown-formatted report
   • Handles success, no-changes, and error scenarios
5. Comment Management:
   • Finds existing token diff comments (if any)
   • Creates new comment or updates existing one
   • Uses unique HTML comment marker for identification

Output Examples

Token Changes Detected

## 🎨 Token Changes Report

**Tokens Changed (5)**

main | **feature-branch**

-------------------------------------------------------------------------------------------

<details open><summary>

**Added (2)**

</summary>

- `color-blue-100`
- `color-blue-200`

</details>

<details open><summary>

**Updated (3)**

</summary>

- `color-red-500`: `#ff0000` -> `#dc2626`
- `spacing-large`: `16px` -> `20px`
- `font-size-body`: `14px` -> `16px`

</details>

---
*This comment was automatically generated by the token diff tool. 🤖*

No Changes

## 🎨 Token Changes Report

No token changes detected in this pull request.

---
*This comment was automatically generated by the token diff tool. 🤖*

Error Scenario

## 🎨 Token Changes Report

⚠️ **Error**: Error generating token diff report. Exit code: 1

Please check the [workflow logs](link-to-logs) for more details.

---
*This comment was automatically generated by the token diff tool. 🤖*

Configuration

Customizing Trigger Paths

To modify which file changes trigger the workflow, update the paths section:

on:
  pull_request:
    types: [opened, synchronize, reopened]
    paths:
      - 'packages/tokens/src/**'        # Token source files
      - 'packages/tokens/schemas/**'    # Schema files
      - 'custom/path/**'                # Add custom paths

Modifying Output Format

The workflow uses the diff-generator's markdown format. To use a different format:

1. Change the --format parameter in the workflow
2. Update the comment body template accordingly

Available formats:

• markdown (default) - Rich markdown with collapsible sections
• handlebars with templates:
  • json - Structured JSON output
  • plain - Plain text format
  • summary - High-level statistics only

Example for JSON format:

pnpm tdiff report \
  --otb ${{ github.base_ref }} \
  --ntb ${{ github.head_ref }} \
  --repo ${{ github.repository }} \
  --format handlebars \
  --template json \
  --output /tmp/token-diff.json

Error Handling

The workflow handles several error scenarios:

1. Diff Generation Failures: Captures exit codes and displays user-friendly error messages
2. No Changes: Displays appropriate "no changes" message
3. Permission Issues: Workflow requires proper permissions for PR comments
4. Network Issues: GitHub API failures are handled by the comment actions

Dependencies

• peter-evans/find-comment@v3: Finds existing comments to update
• peter-evans/create-or-update-comment@v4: Creates or updates PR comments
• actions/checkout@v4: Repository checkout
• moonrepo/setup-toolchain@v0: Automatic Node.js and pnpm setup using project configuration

Troubleshooting

Workflow Not Triggering

1. Check that the PR contains changes to files in the specified paths
2. Verify the workflow file is on the default branch (main)
3. Ensure the repository has Actions enabled

Permission Denied Errors

1. Verify the workflow has pull-requests: write permission
2. Check that the repository settings allow Actions to create/update PR comments
3. For organization repositories, check organization security policies

Diff Generation Errors

1. Check the workflow logs for specific error messages
2. Verify the diff-generator dependencies are correctly installed
3. Ensure the base and head branches exist and are accessible

Comment Not Appearing

1. Check if the workflow completed successfully
2. Verify PR permissions allow bot comments
3. Look for existing comments that might have been updated instead of creating new ones

Maintenance

Updating Dependencies

When updating GitHub Actions or tool versions:

1. Update action versions in the workflow file
2. Node.js and pnpm versions are automatically managed by moonrepo toolchain
3. Update project configuration (moon.yml/package.json) to change tool versions
4. Test the workflow in a development environment

Modifying Comment Format

The comment includes an HTML marker <!-- token-diff-comment --> for identification. When modifying the comment template:

1. Keep the HTML marker intact for proper comment updating
2. Maintain the section structure for consistency
3. Test formatting with various diff scenarios

Integration with Project Standards

This workflow follows the Spectrum Tokens project standards:

• Package Management: Uses pnpm instead of npm
• Node.js Version: Matches project requirement (~20.12)
• Tool Integration: Uses the project's diff-generator tool
• Code Quality: Includes proper error handling and logging
• Documentation: Comprehensive documentation following project patterns