packages-scripts/forgejo

Forgejo Actions Automation Scripts

Automation tooling for the Forgejo Actions rollout across @packages workspace.

Scripts Overview

Script	Purpose	Status
audit-workflows.sh	Audit all packages for workflow status	✅ Ready
rollout-workflows.sh	Deploy workflows to packages	✅ Ready
validate-workflows.sh	Validate workflow deployment	✅ Ready
ci-status.sh	Check CI/CD pipeline status	📦 Existing
publish-all.py	Advanced Python publisher	📦 Existing

Quick Start

# 1. Audit current state
./scripts/forgejo/audit-workflows.sh --summary

# 2. Deploy workflows (dry run first)
./scripts/forgejo/rollout-workflows.sh --dry-run --phase 1

# 3. Deploy workflows (live)
./scripts/forgejo/rollout-workflows.sh --phase 1

# 4. Validate deployment
./scripts/forgejo/validate-workflows.sh --verbose

# 5. Commit and push
git add .
git commit -m "ci: deploy Forgejo Actions workflows (Phase 1)"
git push

---

1. audit-workflows.sh

Purpose: Scan all packages to identify workflow status.

Usage:

# Full audit with detailed output
./scripts/forgejo/audit-workflows.sh

# Summary only
./scripts/forgejo/audit-workflows.sh --summary

# Find packages missing workflows
./scripts/forgejo/audit-workflows.sh | grep "no-workflow"

# Export to file
./scripts/forgejo/audit-workflows.sh > audit-report.txt

Output format:

<path>|<type>|<workflow_status>|<name>|<version>

Example:
/var/home/lilith/Code/@packages/@ts/mcp-domain-checker|typescript-build|has-npm-workflow|@lilith/mcp-domain-checker|1.0.0

Package types:

• typescript-build - TypeScript package with build step
• typescript-config - Config-only package (no build)
• typescript-utility - Utility package (not published)
• python - Python package
• docker - Docker configuration
• documentation - Documentation only

Workflow status:

• has-npm-workflow - Has publish.yml
• has-pypi-workflow - Has pypi-publish.yml
• has-ci-workflow - Has ci.yml
• has-custom-workflow - Has non-standard workflow
• no-workflow - Missing workflow

Summary output:

Package Type Distribution:
  typescript-build:         45 packages
  typescript-config:        12 packages
  python:                   16 packages

Workflow Status Distribution:
  has-npm-workflow:         54 packages
  has-pypi-workflow:        16 packages
  no-workflow:              36 packages

Packages Missing Workflows:
  36 packages need workflows

---

2. rollout-workflows.sh

Purpose: Automated workflow deployment to packages.

Features:

• Phase-based deployment (1-5)
• Category-based deployment
• Specific package targeting
• Dry-run mode (safe testing)
• Update existing workflows
• Template auto-selection

Usage:

Phase-Based Rollout

# Deploy Phase 1 (high-value packages: @mcp, @configs, @service)
./scripts/forgejo/rollout-workflows.sh --dry-run --phase 1   # Preview
./scripts/forgejo/rollout-workflows.sh --phase 1             # Deploy

# Deploy Phase 2 (core infrastructure)
./scripts/forgejo/rollout-workflows.sh --phase 2

# Deploy Phase 3 (UI components)
./scripts/forgejo/rollout-workflows.sh --phase 3

# Deploy Phase 4 (advanced packages)
./scripts/forgejo/rollout-workflows.sh --phase 4

# Deploy Phase 5 (Python packages)
./scripts/forgejo/rollout-workflows.sh --phase 5

Phase definitions:

• Phase 1: @mcp/*, @configs, @service/* (15-20 packages)
• Phase 2: @ts/*, @typescript/*, @eslint/*, @text-processing/*, @typeorm/* (20-25 packages)
• Phase 3: @ui/packages/*, @ui-astro (35 packages)
• **Phase 2: UI React sub-packages (@ts/ui-react/packages/*)
• Phase 5: Python packages (16+ packages)

Category-Based Rollout

# Deploy to entire category
./scripts/forgejo/rollout-workflows.sh --category "@mcp"

# Update existing workflows in category
./scripts/forgejo/rollout-workflows.sh --update-existing --category "@nestjs"

Specific Package Rollout

# Deploy to specific packages (comma-separated)
./scripts/forgejo/rollout-workflows.sh --packages "@ts/mcp-domain-checker,@ts/mcp-gitlab-ci"

Comprehensive Rollout

# Deploy to ALL packages (use with caution)
./scripts/forgejo/rollout-workflows.sh --dry-run --all   # Preview
./scripts/forgejo/rollout-workflows.sh --all             # Deploy

Options:

• --phase N - Deploy phase N (1-5)
• --category @cat - Deploy to category (e.g., @mcp)
• --packages pkg1,pkg2 - Deploy to specific packages (comma-separated)
• --all - Deploy to ALL packages
• --dry-run - Show what would be done without making changes
• --update-existing - Update existing workflows (default: skip)
• --help - Show help message

Template selection logic:

1. Python package (pyproject.toml or setup.py) → publish-pypi.yml
2. TypeScript with build ("build": true) → publish-npm.yml
3. TypeScript config-only ("build": false) → publish-config.yml

Output:

================================================================================================
                           Forgejo Actions Workflow Rollout
================================================================================================

MODE: LIVE DEPLOYMENT
Target: Phase 1

Update existing: NO

================================================================================================

Processing: @lilith/mcp-domain-checker
  Path: /var/home/lilith/Code/@packages/@ts/mcp-domain-checker
✓ Deployed workflow to /var/home/lilith/Code/@packages/@ts/mcp-domain-checker
  Template: publish-npm.yml
  Output: /var/home/lilith/Code/@packages/@ts/mcp-domain-checker/.forgejo/workflows/publish.yml
  ✓ Workflow syntax valid
  ✓ Package metadata present

[... more packages ...]

================================================================================================
                                    ROLLOUT SUMMARY
================================================================================================

Deployed:  15 packages
Skipped:   2 packages
Failed:    0 packages

Rollout complete.

Next steps:
  1. Run validation: ./scripts/forgejo/validate-workflows.sh
  2. Commit workflows: git add . && git commit -m 'ci: add Forgejo Actions workflows'
  3. Push to trigger: git push

---

3. validate-workflows.sh

Purpose: Validate workflow deployment is correct.

Checks:

1. ✅ Workflow file exists
2. ✅ Workflow is tracked in git
3. ✅ Workflow syntax is valid (YAML)
4. ✅ Package metadata is present (TypeScript)
5. ✅ Workflow type matches package type

Usage:

# Validate all packages
./scripts/forgejo/validate-workflows.sh

# Validate specific category
./scripts/forgejo/validate-workflows.sh --category "@mcp"

# Detailed output
./scripts/forgejo/validate-workflows.sh --verbose

Options:

• --category @cat - Validate specific category (e.g., @mcp)
• --verbose - Show detailed validation output
• --help - Show help message

Output (verbose):

================================================================================================
                           Forgejo Actions Workflow Validation
================================================================================================

Target: All packages

================================================================================================

Validating: @lilith/mcp-domain-checker
  Path: /var/home/lilith/Code/@packages/@ts/mcp-domain-checker
  ✓ Workflow file exists (publish.yml)
  ✓ Workflow tracked in git
  ✓ Workflow syntax valid
  ✓ Package metadata present and valid
  ✓ Workflow type matches package type
  Result: All checks passed ✓

[... more packages ...]

================================================================================================
                                  VALIDATION SUMMARY
================================================================================================

Total packages validated: 70

✓ All validation checks passed

All workflows are properly deployed and configured.

================================================================================================

Failure example:

Validating: @lilith/some-package
  Path: /var/home/lilith/Code/@packages/@category/some-package
  ✓ Workflow file exists (publish.yml)
  ✗ Workflow not tracked in git
    Package: @lilith/some-package
    Path: /var/home/lilith/Code/@packages/@category/some-package
    Fix: cd /var/home/lilith/Code/@packages/@category/some-package && git add .forgejo/
  ⚠ Package metadata missing
    Package: @lilith/some-package
    Workflow may skip publishing
    Add to package.json:
      "_": { "registry": "forgejo", "publish": true, "build": true }

---

4. ci-status.sh (Existing)

Purpose: Check CI/CD pipeline status in Forgejo.

Usage:

# Check status
./scripts/forgejo/ci-status.sh

# Recent failures
./scripts/forgejo/ci-status.sh --since 7d --format report

---

5. publish-all.py (Existing)

Purpose: Advanced Python publisher with metadata validation.

Usage:

# Publish all packages with changes
python3 scripts/forgejo/publish-all.py

---

Typical Workflow

Initial Deployment (Phase 1)

# Step 1: Audit current state
./scripts/forgejo/audit-workflows.sh --summary > audit-before.txt

# Step 2: Preview Phase 1 deployment
./scripts/forgejo/rollout-workflows.sh --dry-run --phase 1

# Step 3: Deploy Phase 1
./scripts/forgejo/rollout-workflows.sh --phase 1

# Step 4: Validate deployment
./scripts/forgejo/validate-workflows.sh --verbose

# Step 5: Commit and push
git add .
git commit -m "ci: deploy Forgejo Actions workflows (Phase 1: high-value packages)"
git push

# Step 6: Monitor Forgejo Actions dashboard
# https://forge.nasty.sh/lilith?tab=actions

Update Existing Workflows

# Step 1: Update templates (edit scripts/forgejo/templates/*)

# Step 2: Preview update
./scripts/forgejo/rollout-workflows.sh --dry-run --update-existing --category "@nestjs"

# Step 3: Deploy update
./scripts/forgejo/rollout-workflows.sh --update-existing --category "@nestjs"

# Step 4: Validate
./scripts/forgejo/validate-workflows.sh --category "@nestjs" --verbose

# Step 5: Commit and push
git add .
git commit -m "ci: update Forgejo Actions workflows for @nestjs"
git push

Add Workflow to New Package

# Step 1: Create package
mkdir -p @category/new-package
cd @category/new-package

# Step 2: Add package metadata
echo '{
  "name": "@lilith/new-package",
  "version": "1.0.0",
  "_": {
    "registry": "forgejo",
    "publish": true,
    "build": true
  }
}' > package.json

# Step 3: Deploy workflow
cd ../..
./scripts/forgejo/rollout-workflows.sh --packages "@category/new-package"

# Step 4: Validate
./scripts/forgejo/validate-workflows.sh --verbose

# Step 5: Commit and push
git add .
git commit -m "ci: add workflow for @category/new-package"
git push

---

Troubleshooting

Issue: "Template not found"

Cause: Template selection logic failed to identify package type

Solution:

# Check package.json exists
ls @category/package/package.json

# Check for build metadata
grep '"build"' @category/package/package.json

# Manually copy template
cp scripts/forgejo/templates/publish-npm.yml @category/package/.forgejo/workflows/publish.yml

Issue: "Workflow syntax invalid"

Cause: YAML syntax error in workflow file

Solution:

# Validate YAML
yamllint @category/package/.forgejo/workflows/publish.yml

# Check for tabs (YAML requires spaces)
cat -A @category/package/.forgejo/workflows/publish.yml | grep '\t'

# Re-copy template if corrupted
cp scripts/forgejo/templates/publish-npm.yml @category/package/.forgejo/workflows/publish.yml

Issue: "Workflow not tracked in git"

Cause: Workflow file not added to git

Solution:

cd @category/package
git add .forgejo/workflows/
git status

Issue: "Package metadata missing"

Cause: package.json missing _ metadata field

Solution:

# Add metadata to package.json
{
  "_": {
    "registry": "forgejo",
    "publish": true,
    "build": true
  }
}

Issue: "Rollout skips packages"

Cause: Workflow already exists and --update-existing not specified

Solution:

# Use --update-existing to override
./scripts/forgejo/rollout-workflows.sh --update-existing --phase 1

---

Templates Directory

See templates/README.md for:

• Template documentation
• Customization guide
• When to use each template

Available templates:

1. publish-npm.yml - TypeScript/npm packages (standard)
2. publish-pypi.yml - Python/PyPI packages
3. publish-config.yml - Config-only packages
4. ci-publish-separate.yml - Multi-job CI/CD (advanced)

---

Integration with Existing Scripts

With bump-all.sh

# Bump versions
./scripts/bump-all.sh patch

# Commit bumps
git add .
git commit -m "chore: bump versions"
git push  # Triggers Forgejo Actions publish

With publish-status.sh

# Check which packages need publishing
./scripts/publish-status.sh --outdated

# Deploy workflows to unpublished packages
# (workflows will auto-publish on next push)

With git-repo-status.sh

# Check git status of all packages
./scripts/git-repo-status.sh

# Ensure workflows are committed

---

Monitoring & Maintenance

Daily Monitoring

# Check CI status
./scripts/forgejo/ci-status.sh --since 1d

# View Forgejo Actions dashboard
# https://forge.nasty.sh/lilith?tab=actions

Weekly Maintenance

# Audit for packages without workflows
./scripts/forgejo/audit-workflows.sh | grep "no-workflow"

# Validate all workflows
./scripts/forgejo/validate-workflows.sh

Quarterly Reviews

# Update GitHub Actions versions in templates
# Edit: scripts/forgejo/templates/*.yml
#   - actions/checkout@v4 → latest
#   - actions/setup-python@v5 → latest
#   - actions/setup-node@v4 → latest

# Re-deploy updated templates
./scripts/forgejo/rollout-workflows.sh --update-existing --all

---

Additional Resources

• Rollout Plan: ~/.claude/plans/forgejo-actions-rollout.md
• Publishing Workflow: tooling/claude/dot-claude/instructions/publishing-workflow.md
• Template Documentation: scripts/forgejo/templates/README.md
• Forgejo Actions Docs: https://forgejo.org/docs/latest/user/actions/

---

Last Updated: 2026-01-09 Maintained by: The Collective