<!--
Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>

This file is part of a Moko Consulting project.

SPDX-License-Identifier: GPL-3.0-or-later

# FILE INFORMATION
DEFGROUP: MokoStandards.Documentation.API
INGROUP: MokoStandards.Documentation
REPO: https://git.mokoconsulting.tech/MokoConsulting/MokoStandards-API
PATH: /docs/api/automation/index.md
VERSION: 04.06.00
BRIEF: API reference for automation scripts in api/automation/
-->

# Automation Scripts

Scripts in `api/automation/` orchestrate large-scale operations across multiple
repositories. They require a GitHub PAT (`GH_TOKEN`) with appropriate scopes.

---

## bulk_sync.php

Enterprise-grade bulk synchronization. Reads repository definitions from
`api/definitions/sync/`, applies template files to governed repositories,
and opens Pull Requests with the changes.

**Base class:** `CLIApp`

```bash
# Dry-run sync for the entire org
php api/automation/bulk_sync.php --org MokoConsulting --dry-run

# Sync specific repositories
php api/automation/bulk_sync.php --org MokoConsulting --repos "repo-a,repo-b"

# Exclude repos and skip archived
php api/automation/bulk_sync.php --org MokoConsulting --exclude "legacy-repo" --skip-archived

# Auto-approve PRs (non-interactive)
php api/automation/bulk_sync.php --org MokoConsulting --yes
```

| Option | Description |
|--------|-------------|
| `--org <name>` | GitHub organization to sync |
| `--repos <list>` | Comma-separated list of specific repositories |
| `--exclude <list>` | Repositories to skip |
| `--skip-archived` | Skip archived repositories |
| `--yes` | Approve all PRs without prompting |
| `--dry-run` | Preview changes without creating PRs |
| `--verbose` / `-v` | Verbose output |
| `--help` / `-h` | Show help and exit |

**Related:** See [Bulk Repo Sync](../../bulk-repo-sync-override-files.md) for
override file conventions.

---

## push_files.php

Targeted file push tool. Pushes one or more specific files from MokoStandards
templates to remote repositories without running a full sync. Supports both
definition-based lookup and arbitrary `source:destination` pairs.

```bash
# Push a single file to one repo
php api/automation/push_files.php --files=.github/ISSUE_TEMPLATE/config.yml --repos=MokoCRM

# Push multiple files to multiple repos
php api/automation/push_files.php --files=".github/workflows/ci.yml,.github/workflows/codeql-analysis.yml" --repos=MokoCRM,WaasComponent

# Push directly to a branch (no PR)
php api/automation/push_files.php --files=templates/foo.txt:docs/foo.txt --repos=MyRepo --direct --branch=main
```

| Option | Description |
|--------|-------------|
| `--org <name>` | GitHub organization (default: MokoConsulting) |
| `--repos <list>` | Target repositories — comma-separated (required) |
| `--files <list>` | Files to push — destination paths or `source:dest` pairs (required) |
| `--message <msg>` | Custom commit message |
| `--branch <name>` | Target branch for `--direct` pushes |
| `--direct` | Push directly instead of creating a PR |
| `--yes` | Auto-confirm without prompting |
| `--no-issue` | Skip creating a tracking issue |

---

## repo_cleanup.php

Enterprise repository cleanup. Comprehensive maintenance for governed repos:
delete stale sync branches, close superseded PRs, close resolved tracking
issues, delete retired workflows, clean workflow logs, verify labels, and
detect version drift.

```bash
# Preview all cleanup operations
php api/automation/repo_cleanup.php --all --dry-run

# Run all operations on specific repos
php api/automation/repo_cleanup.php --repos "MokoCRM MokoWaas" --all --yes

# Delete retired workflow files only
php api/automation/repo_cleanup.php --delete-retired --yes

# Close resolved issues and clean old logs
php api/automation/repo_cleanup.php --close-issues --clean-logs --log-days=14 --yes

# Check version drift across all repos
php api/automation/repo_cleanup.php --check-drift --json
```

| Option | Description |
|--------|-------------|
| `--org <name>` | GitHub organization |
| `--repos <list>` | Specific repositories (space-separated) |
| `--skip-archived` | Skip archived repositories |
| `--close-issues` | Close resolved tracking issues |
| `--lock-old-issues` | Lock issues closed >30 days |
| `--clean-workflows` | Delete cancelled/stale workflow runs |
| `--clean-logs` | Delete workflow run logs older than `--log-days` |
| `--log-days <n>` | Days to keep logs (default: 30) |
| `--delete-retired` | Delete retired workflow files from repos |
| `--check-labels` | Verify mokostandards label exists |
| `--check-drift` | Check for version drift against README.md |
| `--all` | Run all cleanup operations |
| `--yes` | Auto-confirm prompts |
| `--dry-run` | Preview changes without making them |
| `--json` | Output results as JSON |

---

**Location:** `docs/api/automation/`
**Mirrors:** `api/automation/`
**Last Updated:** 2026-04-04