Laravel Nova Mirror Laravel Package

Getting Started

• Install as a dev dependency — this is build/sync tooling, not runtime code:

  composer require --dev swisnl/laravel-nova-mirror
  

• Publish the config and inspect it first. The package is configured almost entirely through config/nova-mirror.php:

  php artisan vendor:publish --provider="SwisNL\NovaMirror\NovaMirrorServiceProvider"
  

  Read every key before running anything — the config holds your Nova credentials, the target git remote, the working/clone path, and the branch/tag settings.
• Prepare the target git repository before the first run. Create an empty repo on GitHub/GitLab, generate a token or deploy key with write access, and store the URL + token in .env (e.g. NOVA_MIRROR_REPOSITORY, NOVA_MIRROR_TOKEN). Never commit these.
• Provide Nova credentials the same way Laravel Nova itself expects them for downloads (email + password on older Nova, a license/token on newer Nova). Again, .env only.
• Run the command once by hand so you can watch what happens. The package ships a single artisan command — confirm the exact name via php artisan list | grep -i nova (it is typically nova:mirror):

  php artisan nova:mirror
  

  Inspect the resulting commit(s), the branch name, and whether releases are tagged. That one run tells you more about the config than the README does.
• First real use case: point the command at a mirror repo, run it once, and confirm git log shows the Nova release contents. Then wire it into the scheduler (below) and switch one project's composer.json to consume Nova from your mirror instead of nova.laravel.com.

Implementation Patterns

• Scheduled mirror on a dedicated host. Add the command to app/Console/Kernel.php and run it nightly. Git must be installed, SSH keys/known_hosts configured, and the host must be the only place this runs:

  $schedule->command('nova:mirror')
      ->dailyAt('03:00')
      ->withoutOverlapping()
      ->onOneServer();
  

• CI-driven sync (recommended over a cron box). A scheduled GitHub Actions / GitLab CI job is cleaner: secrets hold the Nova credentials and a deploy key; the job runs composer install on a throwaway runner, executes php artisan nova:mirror, and pushes. This avoids maintaining a long-lived server whose git/SSH setup you have to keep patched.
• Consume the mirror via Composer. In each consuming app, add the mirror as a VCS repository, then composer require laravel/nova:

  "repositories": [
    { "type": "vcs", "url": "[email protected]:acme/nova-mirror.git" }
  ]
  

  If the mirror is private, add its credentials to COMPOSER_AUTH / auth.json in CI too — Composer needs to authenticate to the mirror just as it did to nova.laravel.com.
• Tag every mirrored release. Version constraints (^1.0, ~1.2) only work if releases are tagged. If the package doesn't tag for you, wrap the command in your own artisan command that runs the mirror, reads the Nova version from the release, and git tags it before pushing. This is the single most valuable extension: untagged mirrors force every consumer to pin a commit hash.
• Central mirror across multiple projects. Keep one mirror repo per major Nova line, and have all of your apps point at it. This centralizes license handling, gives you a single audit trail, and means a new project is one repositories entry away.
• Treat git log as the audit trail. Because each release is a commit, git log --oneline is your changelog and git diff <tag1>..<tag2> is your upgrade review. This is the real reason teams adopt the mirror: it turns a black-box commercial dependency into a reviewable, diffable history you can gate deploys on.
• Wrap the command for post-processing. A thin custom command around the mirror call lets you add checksum verification, Slack/Teams notifications on new releases, a security scan of the release contents before it is pushed, and automatic tag creation in one place.

Gotchas and Tips

• This package is archived (last release 2018-09-14), and that matters. It was built against Laravel Nova 1.x. Nova's distribution and authentication changed substantially in later majors (license-key/token flows, changed download endpoints). Expect to patch the config or the HTTP call for Nova 2+. Verify against your Nova version before depending on it; if the download returns 403/404, the endpoint logic has almost certainly aged out.
• Plan to fork it. "Archived" means no upstream fixes and no compatibility updates. Pin the version in composer.json, fork it into your org if you need to maintain the endpoint logic, and treat your fork as own code.
• Credentials leak easily. Nova credentials and the git token are the two things you must keep out of the config file and out of the mirror commits. Use .env locally and CI secrets in the pipeline. Double-check the published config for any hard-coded defaults before committing it.
• Token scopes trip people up. Fine-grained GitHub tokens need Contents: read & write on the mirror repo; classic tokens and deploy keys need to bypass branch protection if you push to a protected branch. A 403 on push with valid credentials is almost always scope or branch-protection.
• Git repository growth is the hidden cost. Composer's VCS driver clones the entire history. A long chain of large release zips means every composer install in every project pays for it. Keep history lean: consider one mirror repo per major version, periodically squash old history, or use a Composer artifact repository instead of VCS.
• Retagging breaks Composer's cache. If you rewrite or move a tag, Composer may keep serving the old commit. Clear with composer clearcache and re-run composer update laravel/nova; otherwise you'll debug a "stale version" that isn't stale at all.
• Handle "nothing to commit" gracefully. A scheduled job that runs nightly will frequently find no new release. Make sure your wrapper command exits 0 in that case, or your CI will be permanently red.
• Avoid concurrent runs. Two overlapping jobs racing on the same working directory and remote will corrupt the clone or fail the push. withoutOverlapping() on the scheduler and a CI concurrency group both protect against this.
• Debugging recipe: run php artisan nova:mirror -v, then cd into the configured working/clone path and run the git commands manually. Most failures are environmental — wrong remote URL, missing SSH agent, known_hosts not populated on a fresh runner, or git not installed on the cron box. Tail storage/logs/laravel.log for the HTTP/exception detail the command swallows.
• Extension points are limited (it's a small, old package), but the useful ones are: publish and edit the config (paths, remote, branch), subclass/override the command and bind it in a service provider, and wrap the whole thing in your own artisan command as described above. The wrapper approach is the pragmatic answer to almost every gap.
• Check the license terms, not just the code license. Make sure your organization's use of a Nova mirror is consistent with the Laravel Nova license and your own compliance policy — the package solves the mechanics, not the legal question.