This workflow automatically synchronizes documentation from the genlayerlabs/genlayer-node repository to this documentation repository.

1. Repository Dispatch: Can be triggered from the genlayer-node repository
2. Manual Workflow Dispatch: Can be manually triggered from the Actions tab

1. Prepare: Detects version from input or automatically finds latest tag
2. Sync Files (parallel matrix strategy, 6 sync types):
   • Changelog files → content/validators/changelog/
   • Config file → content/validators/config.yaml
   • Docker Compose file → content/validators/docker-compose.yaml
   • API gen method docs → pages/api-references/genlayer-node/gen/ (filtered by regex)
   • API debug method docs → pages/api-references/genlayer-node/debug/ (filtered by regex)
   • API ops method docs → pages/api-references/genlayer-node/ops/
3. Aggregate Results: Merges all synced files from parallel jobs into single artifact
4. Generate Docs:
   • Applies synced files to specific directories (avoids deleting unrelated content)
   • Runs documentation generation scripts to create pages/validators/ files
5. Create PR:
   • Creates branch, commits changes, and creates/updates pull requests
   • Includes detailed summary with file counts
6. Summary: Generates comprehensive workflow summary with detailed file lists
7. Cleanup: Automatically removes all intermediate artifacts when enabled

Important Notes:

• Both .md and .mdx files are supported, automatically renamed to .mdx when synced
• README and CHANGELOG files are excluded from sync operations
• Regex filtering uses Perl-compatible patterns (supports negative lookahead)
• File deletions are properly handled with rsync --delete for each directory

Add this to a workflow in the genlayer-node repository:

- name: Trigger docs sync
  uses: peter-evans/repository-dispatch@v2
  with:
    token: ${{ secrets.DOCS_REPO_TOKEN }}
    repository: genlayerlabs/genlayer-docs
    event-type: sync-docs
    client-payload: |
      {
        "version": "${{ steps.get_version.outputs.version }}",
        "changelog_path": "docs/changelog",
        "api_gen_path": "docs/api/rpc",
        "api_debug_path": "docs/api/rpc",
        "api_ops_path": "docs/api/ops",
        "api_gen_regex": "gen_(?!dbg_).*",
        "api_debug_regex": "gen_dbg_.*"
      }

• GITHUB_TOKEN: Automatically provided by GitHub Actions, no setup needed. Used for:
  • Repository checkout
  • Creating pull requests via GitHub CLI (automatically detected by gh)
  • General workflow authentication

Access to the private genlayerlabs/genlayer-node repository is provided by a GitHub App installed on that repository. The workflow mints a short-lived installation token via actions/create-github-app-token@v3.

Credentials live in the Node Sync GitHub Environment (Settings → Environments → Node Sync), which has a Required-reviewers protection rule. To keep the gate to a single approval per workflow run, only the prepare job declares environment: Node Sync; it mints the App token once and exposes it as a job output (needs.prepare.outputs.token) for downstream jobs to consume. Adding a second job that declares the same environment would trigger a second approval — avoid that.

Required environment secrets:

• NODE_SYNC_APP_CLIENT_ID: Client ID of the GitHub App
• NODE_SYNC_APP_KEY: PEM-encoded private key of the GitHub App

The App must be installed on genlayerlabs/genlayer-node with at least Contents: Read permission. Tokens are scoped to that single repository at mint time.

• DOCS_REPO_TOKEN (in genlayer-node): Token with repo scope for triggering this workflow. Used for:
  • Triggering repository dispatch events from genlayer-node
  • Must have repo scope to trigger workflows
  • Add this as a secret in the genlayer-node repository

From the Actions tab:

1. Select "Sync Documentation from Node Repository"
2. Click "Run workflow"
3. Specify parameters:
   • Version (optional, default: latest) - Version/tag to sync (e.g., v0.3.5, or "latest" to auto-detect)
   • Changelog path (optional, default: docs/changelog)
   • API gen path (optional, default: docs/api/rpc)
   • API debug path (optional, default: docs/api/rpc)
   • API ops path (optional, default: docs/api/ops)
   • API gen regex (optional, default: gen_(?!dbg_).*)
   • API debug regex (optional, default: gen_dbg_.*)

docs/
├── changelog/
│   ├── v0.3.4.md       # Will be copied as v0.3.4.mdx
│   ├── v0.3.5.mdx      # Will be copied as-is
│   └── ...
├── api/
│   ├── rpc/
│   │   ├── gen_call.md              # API gen: copied as gen_call.mdx
│   │   ├── gen_getContractSchema.mdx # API gen: copied as-is
│   │   ├── gen_dbg_ping.md          # API debug: copied as gen_dbg_ping.mdx
│   │   └── ...
│   └── ops/
│       ├── health.md       # API ops: copied as health.mdx
│       ├── metrics.mdx     # API ops: copied as-is
│       └── ...
configs/
└── node/
    └── config.yaml.example     # Will be copied to content/validators/config.yaml
release/
└── docker-compose.yaml         # Will be copied to content/validators/docker-compose.yaml

The source paths and filters can be customized via workflow_dispatch inputs:

• changelog_path: Path to changelog files (default: docs/changelog)
• api_gen_path: Path to API gen methods (default: docs/api/rpc)
• api_debug_path: Path to API debug methods (default: docs/api/rpc)
• api_ops_path: Path to API ops methods (default: docs/api/ops)

• api_gen_regex: Regex pattern to filter gen API files (default: gen_(?!dbg_).*)
  • This default pattern matches files starting with gen_ but excludes those starting with gen_dbg_
• api_debug_regex: Regex pattern to filter debug API files (default: gen_dbg_.*)
  • This default pattern matches only files starting with gen_dbg_

Note: API ops sync includes all files (no regex filtering applied), except README files which are automatically excluded.

The workflow uses 7 main jobs with the following dependency chain:

prepare (version detection)
    ↓
sync-files (matrix: 6 parallel jobs)
    ↓
aggregate-results (merges artifacts)
    ↓
generate-docs (runs npm scripts)
    ↓
create-pr (commits & creates PR)
    ↓ 
summary (always runs, shows results)
    ↓ 
cleanup (removes all artifacts if enabled)

The workflow uses environment variables for global settings:

• CLEANUP_ARTIFACTS: true - Enables automatic cleanup of intermediate artifacts after successful completion

The workflow uses composite actions for code reusability:

• .github/actions/sync-files/ - Handles all file synchronization types

• .github/actions/sync-files/sync.sh - Core sync logic with file tracking and deletion support
• .github/scripts/sync-artifact-files.sh - Applies synced files to repository with rsync --delete
• .github/scripts/aggregate-reports.sh - Aggregates sync metrics from parallel jobs
• .github/scripts/git-utils.sh - Branch creation, commit, and push operations
• .github/scripts/version-utils.sh - Version detection and validation
• .github/scripts/doc-generator.sh - Wrapper for npm documentation generation
• .github/scripts/sanitize-config.sh - Sanitizes config file (replaces RPC URLs and provider)
• .github/scripts/sanitize-docker-compose.sh - Removes alloy service and volumes from docker-compose

The config sync process includes automatic sanitization using yq:

• URL Replacement: RPC URLs and provider replaced with TODO placeholders

The docker-compose sync process includes automatic sanitization using yq and sed:

• Alloy Service Removal: The alloy monitoring service is removed
• Volumes Removal: The volumes section is removed
• Comment Cleanup: Alloy-related comments are removed

Sync branches follow the pattern: docs/node/{version}

• Example: docs/node/v0.3.5
• Version slashes are replaced with dashes for safety

The workflow uses artifacts to pass data between jobs:

• synced-{type} - Individual sync results for each type (includes files and reports)
• synced-merged - All synced files and reports merged together
• synced-final - Final artifact with generated documentation and sync reports

Artifact Structure:

• Each artifact contains:
  • sync_report_{type}.md - Detailed report with file lists
  • Synced files in their target directory structure
  • sync-reports/ directory in final artifact for reference

Deletion Handling:

• Uses rsync --delete for each specific subdirectory to ensure proper file deletion
• Only affects synced directories (content/validators/, pages/api-references/genlayer-node/)
• Never deletes unrelated documentation content

Automatic Cleanup:

• All artifacts are automatically deleted when CLEANUP_ARTIFACTS: true (default)
• Cleanup only runs after successful PR creation or summary generation

• Creates new PR for new versions
• Updates existing open PR for same version
• Automatically labels with "documentation" and "node"

PR Description includes:

• Source repository and version
• API filter patterns used
• Total files changed with breakdown (added/updated/deleted)
• List of npm scripts that were run
• Automated checklist confirming successful sync

The summary job generates a comprehensive report in the GitHub Actions UI:

• Overall Results: Version and total change counts
• Sync Results by Type: For each sync type shows:
  • Count of added/updated/deleted files
  • Detailed file lists (e.g., "Added: gen_call.mdx")
• Pull Request Link: Direct link to created/updated PR

After syncing files, the workflow runs these npm scripts:

• npm run node-generate-changelog - Generates changelog page from synced files
• npm run node-update-setup-guide - Updates setup guide with version info
• npm run node-update-config - Updates config.yaml example in setup guide
• npm run node-update-docker-compose - Updates docker-compose.yaml example in setup guide
• npm run node-generate-api-docs - Generates API reference pages