GitHub Workflows Documentation

This document explains the CI/CD system for the Asset Tokenization Studio (ATS) monorepo, including development workflow, release processes, and how to work with changesets.

Overview

The repository uses Changesets for version management with independent release cycles for:

• ATS Project: Asset Tokenization Studio (contracts, SDK, web app)
• Mass Payout Project: Mass payout functionality

All development happens on the develop branch with automated testing, changeset validation, and manual release controls by authorized teams.

How to test github workflows locally

To be able to test github workflows locally you can use act, a github actions simulator act homepage

Install act

curl --proto '=https' --tlsv1.2 -sSf https://raw.githubusercontent.com/nektos/act/master/install.sh | sudo bash

Run workflow

Substitute <workflow> for the workflow you want to test (ats.pubilsh, mp.release, ...)

./bin/act workflow_dispatch \
  -W .github/workflows/<workflow>.yml \
  --input dry-run-enabled=true \
  -s NPM_TOKEN=fake_token \
  -P token-studio-linux-large=catthehacker/ubuntu:act-latest

Developer Workflow

Daily Development Process

sequenceDiagram
    participant D as develop
    participant F as feature/branch
    participant M as main
    participant F1 as feature/branch-main

    Note over D,M: Daily Development Pattern

    D->>F: Create feature branch
    Note over F: Code changes + changeset
    F->>D: PR with changeset (tests + validation)
    Note over D: Accumulate features

    D->>F1: Create branch from develop
    Note over F1: Same changes (no changeset needed)
    F1->>M: PR to main (ready for release)
    Note over M: Production-ready code

Loading

Step-by-Step Guide

1. Create feature branch from develop:

   git checkout develop && git pull origin develop
   git checkout -b feature/your-feature-name

2. Make your changes to ATS or Mass Payout packages

3. Create changeset (required for all PRs):

   npm run changeset

   • Select affected packages
   • Choose change type (patch/minor/major)
   • Write clear description

4. Commit with DCO and Signature compliance:

Commit messages should comply with the conventional commits standard

git add .
git commit --signoff -S -m "feat: your commit message"
git push origin feature/your-feature-name

5. Open PR to develop branch - automated checks will run

Bypass Changeset Validation

For non-feature changes, add these labels to skip changeset requirement:

• no-changeset: Configuration or documentation changes
• docs-only: Documentation-only changes
• chore: Build system or dependency updates
• hotfix: Emergency fixes

Workflow Reference

Automated Workflows

Workflow	Trigger	Purpose
ATS Tests	PR to main, ATS file changes	Run ATS contracts, SDK, and web tests
Mass Payout Tests	PR to main, MP file changes	Run Mass Payout package tests
Changeset Check	PR to develop	Validate changeset or bypass labels

Manual Release Workflows

Workflow	Purpose	Authorized Teams
ATS Release	Version ATS packages, create release	platform-ci, release-engineering-managers, iobuilders-hedera
Mass Payout Release	Version MP packages, create release	platform-ci, release-engineering-managers, iobuilders-hedera

Automatic Publishing

Workflow	Trigger	Purpose
ATS Publish	Release tag *-ats	Publish ATS packages to npm
Mass Payout Publish	Release tag *-mp	Publish MP packages to npm

Release Process

The repository supports two release approaches:

1. Automated Release Workflows (recommended for most releases)
2. Manual Release Branches (alternative for complex releases or when automation is unavailable)

Option 1: Automated Release Workflows

ATS Release Flow

sequenceDiagram
    participant Dev as Developer
    participant M as main
    participant GH as GitHub Actions
    participant NPM as NPM Registry

    Dev->>GH: Trigger ATS Release Workflow
    GH->>GH: Validate ATS changesets exist
    GH->>M: Run changeset version --ignore MP
    GH->>M: Commit version changes to main
    GH->>M: Create tag v1.16.0-ats
    GH->>GH: Create GitHub release
    GH->>NPM: Auto-trigger publish workflow
    NPM->>NPM: Publish contracts & SDK

Loading

Mass Payout Release Flow

sequenceDiagram
    participant Dev as Developer
    participant M as main
    participant GH as GitHub Actions
    participant NPM as NPM Registry

    Dev->>GH: Trigger MP Release Workflow
    GH->>GH: Validate MP changesets exist
    GH->>M: Run changeset version --ignore ATS
    GH->>M: Commit version changes to main
    GH->>M: Create tag v2.4.0-mp
    GH->>GH: Create GitHub release
    GH->>NPM: Auto-trigger publish workflow
    NPM->>NPM: Publish MP packages

Loading

Release Options

Both automated workflows support:

• Preview Mode: Shows what would be released (dry-run)
• Release Mode: Actually creates releases and triggers publishing

Option 2: Manual Release Branches

For complex releases or when automation is unavailable, you can use the traditional manual release branch approach:

sequenceDiagram
    participant M as main
    participant D as develop
    participant F as feat/example
    participant F1 as feat/example-main
    participant R as release/v1.22.2-ats

    Note over M,D: Initial state

    loop for each feature in sprint
        D->>F: Create feature branch
        Note over F: Feature development + changeset
        F->>D: Merge PR with changeset

        D->>F1: Create branch from develop
        F1->>M: Merge PR directly to main
    end

    M->>R: Create release branch
    Note over R: Run: npx changeset version
    Note over R: Generate changelogs + version bump
    R->>M: Merge version commit to main

    Note over M: Create tag v1.22.2-ats
    Note over M: Manual GitHub release
    Note over M: Automatic NPM publish via workflow

    M->>D: Merge main back to develop

Loading

Manual Release Steps

1. Create release branch from main:

   git checkout main && git pull origin main
   git checkout -b release/v1.22.2-ats

2. Apply changesets and version packages:

   # For ATS release
   npx changeset version --ignore "@hashgraph/mass-payout*"
   
   # For Mass Payout release
   npx changeset version --ignore "@hashgraph/asset-tokenization-*"

3. Commit version changes:

   git add .
   git commit --signoff -S -m "chore: release v1.22.2-ats"
   git push origin release/v1.22.2-ats

4. Merge release branch to main:

   • Create PR from release/v1.22.2-ats to main
   • Review and merge the version changes

5. Create GitHub release:

   • Create tag v1.22.2-ats on main branch
   • Create GitHub release with generated changelog
   • Publishing workflows trigger automatically

6. Sync main back to develop:

   git checkout develop
   git merge main
   git push origin develop

Benefits of Manual Release Branches:

• ✅ Full control over version timing and content
• ✅ Ability to make additional changes during release process
• ✅ Works with existing automated publishing workflows
• ✅ Suitable for complex releases requiring manual intervention

Release Authorization

Only these teams can trigger releases:

• platform-ci
• platform-ci-committers
• release-engineering-managers
• developer-advocates
• iobuilders-hedera
• Users containing hashgraph

Workflow Interactions

sequenceDiagram
    participant D as develop
    participant M as main
    participant GH as GitHub Actions
    participant NPM as NPM Registry

    Note over D,M: Workflow Overview

    loop Feature Development
        Note over D: Features merge to develop
        Note over D: Changesets accumulate
        D->>M: Feature PRs to main
    end

    Note over M: Ready for release
    M->>GH: Manual release trigger
    GH->>M: Version packages + create tag
    GH->>GH: Create GitHub release
    GH->>NPM: Auto-trigger publish
    NPM->>NPM: Publish to NPM

    M->>D: Sync version changes back

Loading

Troubleshooting

Common Issues

❌ Changeset check failed

• Solution: Create changeset with npm run changeset or add bypass label

❌ "No changesets found to be bumped"

• Solution: Ensure changesets exist for the project you're releasing
• Use npm run changeset:status to check pending changes

❌ Release workflow unauthorized

• Solution: Ensure you're member of authorized teams listed in CODEOWNERS

❌ Tests failing on PR

• Solution: Run npm run ats:test or npm run mass-payout:test locally
• Fix failing tests before requesting review

❌ DCO check failed

• Solution: Ensure all commits use --signoff flag:

  git commit --signoff -S -m "your message"

Getting Help

• Changesets documentation: Changesets Intro
• Check pending releases: npm run changeset:status
• Preview releases: npm run release:preview
• Local development: See CLAUDE.md for complete development setup

Quick Commands

# Development
npm run changeset                # Create changeset
npm run changeset:status         # Check pending changes
npm run ats:test                 # Run ATS tests
npm run mass-payout:test         # Run MP tests

# Preview releases
npm run release:preview         # Show all pending releases
npm run release:ats             # Preview ATS release (local)
npm run release:mp              # Preview MP release (local)