Project Sync

Project Sync is a high-performance GitHub Projects v2 automation engine designed to synchronize issues and pull requests across complex, multi-repository organizations with 100% predictability.

Overview

This tool transforms your GitHub Project into a self-driving productivity engine. It eliminates manual board maintenance by implementing a rule-based state machine for:

• Intelligent Intake: Automatically adds PRs and issues to the project board based on authorship, assignment, or repository source.
• Dynamic Workflows: Moves items between columns (e.g., New → Active) based on real-time state changes.
• Sprint Orchestration: Seamlessly manages sprint assignments and rollovers.
• Smart Inheritance: Propagates PR metadata (assignees, sprints, columns) to linked issues.
• Multi-Org Mastery: Monitors activity across bcgov and bcgov-c simultaneously.

Automated Noise Exclusions

To prevent automated noise and metadata artifacts from cluttering the project board, the engine early-skips issues and pull requests matching specific titles before applying rule transitions.

Default Exclusions

By default, the engine excludes:

• Dependency Dashboard (Exact Match): Excludes Renovate or Dependabot organization-wide interactive dashboards.
• ZAP Security Report (Substring Match): Excludes automated vulnerability and security scan reports.
• ZAP Full Scan Report, ZAP Scan Baseline Report, ZAP API Scan Report (Substring Match): Exclude issues opened by the ZAP GitHub Actions (zaproxy/action-full-scan, action-baseline, action-api-scan) under their default titles, and titles that extend them (e.g. ZAP Full Scan Report: <url> from bcgov/actions/scan-url).
• **ZAP: ** (Prefix Match): Excludes ZAP reports opened with a custom issue_title such as ZAP: <name> (e.g. ZAP: backendPy from bcgov/quickstart-openshift-modules).

Custom Exclusions

Teams can customize exclusions in their rules.yml to filter out specific automated noise:

# Exclusion rules to filter out automated noise by title
exclusions:
  exact_titles:
    - "Dependency Dashboard"
    - "My Custom Noise Title"
  title_substrings:
    - "ZAP Security Report"
    - "ZAP Full Scan Report"
    - "ZAP Scan Baseline Report"
    - "ZAP API Scan Report"
    - "[Automated]"
  title_prefixes:
    - "ZAP: "

Strings checked against exact_titles must match the issue or pull request title exactly (trailing/leading whitespaces and carriage returns are automatically trimmed before evaluation). Strings in title_substrings will exclude any item containing that substring, and strings in title_prefixes will exclude any item whose title starts with that prefix. All matches are case-sensitive. All three lists are required in rules.yml; there are no built-in defaults.

Stability & Predictability

We treat stability as a first-class feature. Our "Ludicrous Testing" philosophy ensures that every rule processed is verified against a comprehensive matrix of conditions.

• Hardcoded Validation: We use a strict whitelist-based validator to ensure rule evaluation is 100% predictable and secure against code injection.
• Native Efficiency: Built on Node.js 24 and native ES Modules for lightning-fast, future-proof execution.
• Zero-Network Tests: Our 240+ count test suite runs in pure isolation, guaranteeing that the core logic is bulletproof without ever making a real API call.
• Strict Environments: We enforce Node versions via .npmrc to ensure that every developer and CI runner is perfectly aligned.

Visibility & Auditing

Designed for transparency. Every run provides:

• GitHub Actions Job Summary: A premium Markdown report generated in the Action's summary tab.
• Audit Logs: Detailed console output with a [AUDIT] prefix for all state transitions.
• Precision Metrics: Real-time counters for processed, added, and skipped items.

Configuration

Configure your entire workflow in a single, version-controlled rules.yml file.

Project Connection

The tool resolves your project identity with minimal friction:

project:
  url: https://github.com/orgs/bcgov/projects/16
  # Organization and ID are automatically resolved from the URL

Resource Monitoring

Define which realms the engine should govern:

project:
  allowedOrgs:
    - bcgov
    - bcgov-c

Authentication & Token Setup

The sync engine requires authentication via a repository secret named PROJECT_SYNC_TOKEN configured in your workflow (.github/workflows/sync.yml).

Note on Fine-Grained Tokens: GitHub Fine-Grained PATs do not currently support Projects (v2) permissions under repository or account permissions. Therefore, a Classic Personal Access Token (PAT) is required to authenticate GitHub Projects v2 automation.

Required Classic PAT Scopes

1. Go to GitHub Settings → Developer Settings → Personal Access Tokens → Tokens (classic).
2. Set Note to PROJECT_SYNC_TOKEN.
3. Select the following required scopes:
   • repo (Full control of private repositories - required to access issue and PR metadata across bcgov and bcgov-c. Note: GitHub automatically locks child sub-scopes when repo is selected.)
   • project (Full control of organization and user projects - required for GraphQL projectV2 access).
   • read:org (Read org membership under admin:org - required for org identity resolution).

Adding an assignee requires admin rights on that repository. When GitHub responds Must have admin rights to Repository, the engine logs a warning, leaves the GitHub assignee unchanged, and continues. The item is still added to the project, and its status and sprint are still updated.

Adding the Secret to GitHub Actions

1. Copy the generated token string (ghp_...).
2. Navigate to your repository's Settings → Secrets and variables → Actions.
3. Click New repository secret.
4. Set Name to PROJECT_SYNC_TOKEN and paste your token in Secret.

Development & Specs

This project follows a Spec-Driven Development model using the SpecKit framework.

• SpecKit Architecture: Documentation for our feature specifications lives in the specs/ directory. See the SpecKit README for usage guidelines.
• Rule Engine Spec: See Spec 004 for a deep dive into our validation architecture.
• Project Constitution: Review memory/constitution.md for our core development principles and "Ludicrous Testing" standards.
• AI Pair Programming: See .github/copilot-instructions.md for guidance when working with AI coding assistants.

Search Window & API Usage

Each run searches open issues and PRs, plus PRs closed without merging, updated since the last successful run (the watermark, minus a 10-minute overlap). Without a watermark it falls back to the last 2 hours. Closed and merged items are left to GitHub's built-in project workflows, which move them to Done. Board membership, Status and Sprint come back with the search results, so there are no per-item board lookups, and the monitored repos are combined into as few searches as fit. Each run's job summary shows the API call count and the remaining rate limit.

Catch Up

Normal runs only see items updated since the last successful run. To add older open items that aren't on the board yet (for example after adding repos to repository_scope), go to Actions → Sync → Run workflow, tick Catch up, and run it. From the command line:

gh workflow run sync.yml -R bcgov/project-automator -f catch_up=true

A catch-up runs the normal sync code with the backfill set to all. It searches all open issues and PRs in the monitored repos (and the monitored users' authored, assigned and review-requested items), ignoring the watermark, and applies the same exclusions. It only adds the missing items, in the board_columns.issue.no_status column (New). Items already on the board aren't re-added or moved, and the run doesn't save the watermark. Leave it unticked for a normal run. There's no schedule for it.

Testing

We value exhaustive verification. Run the full suite, including the ludicrous coverage matrix:

npm test

For targeted testing of the core engines:

# Test the unified rule processor
npm test -- test/processors/unified-rule-processor.test.js

# Test the ludicrous validation matrix
npm test -- test/processors/ludicrous-coverage.test.js