Add setup workflow with error handling and fix AddressFactory Faker instance issue

[Copilot]

Creates a debuggable GitHub Actions workflow for installation steps with error collection, and fixes database seeding failure caused by incorrect Faker instance usage.

Setup Workflow (.github/workflows/setup.yml)

• Selective execution: 6 toggleable steps (yarn, composer, env, key:generate, migrate, seed)
• Error resilience: Each step continues on failure using set +e, logs to /tmp/setup_errors.log
• Consolidated reporting: Final step outputs all failures with exit codes and diagnostic hints
• Infrastructure: MariaDB 10.6, PHP 8.4, Node.js 22

Enables debugging specific installation steps by disabling others, while collecting all errors in a single run.

AddressFactory Bug Fix

The factory added custom Faker providers to $this->faker, then used the fake() helper which creates a fresh instance without those providers:

// Before - fails on stateAbbr (en_US\Address provider method)
$this->faker->addProvider(new \Faker\Provider\en_US\Address($this->faker));
return [
    'state_or_province' => fake()->stateAbbr,  // ❌ new instance, no providers
];

// After - uses the instance with custom providers
return [
    'state_or_province' => $this->faker->stateAbbr,  // ✅ has en_US\Address
];

All 8 fields updated to use $this->faker consistently.

Documentation

Added workflow documentation (Section 8 in .github/workflows/README.md) with usage examples and error handling explanation.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• fakerphp.github.io
  • Triggering command: /home/REDACTED/work/_temp/ghcca-node/node/bin/node /home/REDACTED/work/_temp/ghcca-node/node/bin/node --enable-source-maps /home/REDACTED/work/_temp/copilot-developer-action-main/dist/index.js (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

Original prompt

Make a GitHub action that does a simple yarn install, composer install, copy .env.example to menv, php artisan key:generate and php artisan migrate and php artisan db:seed xxx@xxx:/home/users/xxx/www/office.xxx.com# yarn install yarn install v1.22.22 error Error: EISDIR: illegal operation on a directory, read info Visit https://yarnpkg.com/en/docs/cli/install for documentation about do a try/catch for every step and make it possible to choose the steps for debugging purposes. Ob try / catch in the catch part, continue with the rest of the steps, but record what went wrong. Report at the end of all the faults. The addressSeedrrr got another error of "stateAbbr not found" after seeding

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

Summary by CodeRabbit

• Documentation

  • Updated workflow setup documentation with enhanced error handling guidance.

• Chores

  • Improved internal setup workflow with comprehensive error tracking and reporting.

---

Note: This release primarily contains internal infrastructure improvements and documentation updates with no direct impact on end-user functionality.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

Important

Review skipped

Bot user detected.

To trigger a single review, invoke the @coderabbitai review command.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

📝 Walkthrough

Walkthrough

This PR introduces a new GitHub Actions workflow for multi-step setup with granular error handling, updates the workflow documentation to describe the setup process, and refactors the AddressFactory to use $this->faker instead of the fake() helper function.

Changes

Cohort / File(s)	Summary
Workflow Documentation .github/workflows/README.md	Expanded section 8 from "Quickstart" to "Setup & Install with Error Handling," adding detailed workflow trigger, purpose, steps, error handling mechanisms, and usage examples. Renumbered subsequent sections.
New Setup Workflow .github/workflows/setup.yml	Added comprehensive GitHub Actions workflow with MariaDB and PHP 8.4 services, conditional setup steps (Yarn, Composer, .env, key generation, migrations, seeding), per-step error logging to /tmp/setup_errors.log, and final consolidated error reporting.
Factory Refactoring Modules/Clients/Database/Factories/AddressFactory.php	Replaced fake() helper calls with $this->faker-> accessor across all address fields (address_type, address_1, address_2, number, postal_code, city, state_or_province, country).

Sequence Diagram(s)

sequenceDiagram
    participant GitHub as GitHub Actions
    participant MariaDB as MariaDB Service
    participant Yarn as Yarn
    participant Composer as Composer
    participant Env as Environment
    participant Artisan as Laravel Artisan
    participant Log as Error Log
    participant Report as Final Report

    GitHub->>MariaDB: Start service
    GitHub->>Yarn: Conditional: Run yarn install
    Yarn-->>Log: Log errors (if conditional enabled)
    GitHub->>Composer: Conditional: Run composer install
    Composer-->>Log: Log errors (if conditional enabled)
    GitHub->>Env: Conditional: Copy .env.example → .env
    Env-->>Log: Log errors (if conditional enabled)
    GitHub->>Artisan: Conditional: Generate app key
    Artisan-->>Log: Log errors (if conditional enabled)
    GitHub->>Artisan: Conditional: Run migrations
    Artisan-->>Log: Log errors (if conditional enabled)
    GitHub->>Artisan: Conditional: Run seeding
    Artisan-->>Log: Log errors (if conditional enabled)
    GitHub->>Report: Aggregate results from error log
    Report-->>GitHub: Report success or failure

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• InvoicePlane/InvoicePlane-v2#345: Modifies the same AddressFactory.php file to update address field formatters, related through shared factory refactoring work.

Poem

🐰 A workflow springs to life with care,
Steps dancing in the setup air,
Error logs catch every stumble,
While factories refresh and tumble,
Setup smooth from start to end! 🚀

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the two main changes: adding a setup workflow with error handling and fixing an AddressFactory Faker instance issue, matching the changeset content.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[nielsdrost7]

@coderabbitai full review

[coderabbitai]

✅ Actions performed

Full review triggered.

[coderabbitai]

Actionable comments posted: 1

🤖 Fix all issues with AI agents

In @.github/workflows/setup.yml:
- Around line 99-106: The "Initialize error tracking" step (id: init) currently
writes a newline into /tmp/setup_errors.log using echo "" >
/tmp/setup_errors.log which makes the later check if [ -s /tmp/setup_errors.log
] report a false positive; change the initialization to create an empty
zero-byte file instead, e.g. use : > /tmp/setup_errors.log or truncate -s 0
/tmp/setup_errors.log (or rm -f /tmp/setup_errors.log && touch
/tmp/setup_errors.log) so the -s test only triggers when real errors are
appended.

📜 Review details

Configuration used: defaults

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between e620093 and 59e81e9.

📒 Files selected for processing (3)

• .github/workflows/README.md
• .github/workflows/setup.yml
• Modules/Clients/Database/Factories/AddressFactory.php

🧰 Additional context used

📓 Path-based instructions (1)

**/*.php

📄 CodeRabbit inference engine (.github/copilot-instructions.md)

Always use full namespace imports instead of short imports (e.g., use Illuminate\Support\Facades\Log not Log)

Files:

• Modules/Clients/Database/Factories/AddressFactory.php

🧠 Learnings (3)

📚 Learning: 2026-01-08T10:38:10.370Z

Learnt from: CR
Repo: InvoicePlane/InvoicePlane-v2 PR: 0
File: .github/copilot-instructions.md:0-0
Timestamp: 2026-01-08T10:38:10.370Z
Learning: Applies to **/Tests/**/*Export*.php : Export tests must use fakes: `Queue::fake()`, `Storage::fake()`, and verify job dispatching with `Bus::assertChained()`

Applied to files:

• Modules/Clients/Database/Factories/AddressFactory.php

📚 Learning: 2026-01-08T10:38:10.369Z

Learnt from: CR
Repo: InvoicePlane/InvoicePlane-v2 PR: 0
File: .github/copilot-instructions.md:0-0
Timestamp: 2026-01-08T10:38:10.369Z
Learning: Applies to **/Tests/**/*.php : Prefer Fakes and Fixtures over Mocks in tests

Applied to files:

• Modules/Clients/Database/Factories/AddressFactory.php

📚 Learning: 2026-01-08T10:38:10.370Z

Learnt from: CR
Repo: InvoicePlane/InvoicePlane-v2 PR: 0
File: .github/copilot-instructions.md:0-0
Timestamp: 2026-01-08T10:38:10.370Z
Learning: Applies to **/Tests/**/*.php : Add type hints when factories return Collection but method expects Model

Applied to files:

• Modules/Clients/Database/Factories/AddressFactory.php

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)

• GitHub Check: Agent

🔇 Additional comments (6)

Modules/Clients/Database/Factories/AddressFactory.php (1)

28-35: LGTM! Correct fix for the Faker provider issue.

The changes correctly replace fake() with $this->faker for all address fields. Since custom Faker providers are added to $this->faker (lines 20-25), using the instance method ensures that custom methods like stateAbbr from the en_US\Address provider are available. This resolves the "stateAbbr not found" seeding errors mentioned in the PR.

.github/workflows/setup.yml (4)

1-54: LGTM! Clean workflow structure with well-defined inputs.

The workflow uses workflow_dispatch with six choice-based boolean inputs for granular step control. Using type: choice with string values 'true'/'false' (rather than boolean type) ensures reliable string comparisons in the conditional steps later.

---

55-81: LGTM! Proper service configuration with health checks.

The job configures MariaDB 10.6 with appropriate health checks to ensure the database is ready before the setup steps execute. Database credentials are correctly matched between the service definition and environment variables.

---

107-280: LGTM! Consistent error handling pattern across all setup steps.

All six setup steps follow a consistent and correct pattern:

• Use set +e to prevent early exit on failure
• Capture exit codes for error detection
• Log failures with step name, exit code, and diagnostic hints to /tmp/setup_errors.log
• Set step-specific output flags for the final report
• Always exit 0 to continue to the next step

The commands use appropriate flags for CI environments (e.g., --frozen-lockfile for Yarn, --no-interaction for Composer, --force for migrations).

---

281-372: LGTM! Comprehensive final report with clear status indicators.

The final report step correctly:

• Uses if: always() to ensure it runs regardless of previous step outcomes
• Aggregates all errors from the log file
• Generates a detailed GitHub Step Summary with visual indicators (✅/❌)
• Exits with status 1 if any errors occurred, otherwise 0

Note: The error detection on line 288 depends on the initialization fix suggested earlier to avoid false positives when no errors occur.

.github/workflows/README.md (1)

406-482: LGTM! Comprehensive and accurate documentation.

The new Section 8 documentation accurately describes the setup workflow:

• All six steps match the workflow implementation
• Error handling explanation is correct (uses set +e, logs to /tmp/setup_errors.log, continues on failure)
• Infrastructure details match the workflow configuration (MariaDB 10.6, PHP 8.4, Node.js 22)
• Usage examples provide clear guidance for full setup and selective debugging scenarios
• The step-by-step instructions are easy to follow