Nova Releases Laravel Package

Getting Started

Confirm Nova is present before you install anything. This package renders inside a licensed Laravel Nova deployment — without Nova it is not usable at all. It is archived (last release v1.0.0, 2020-09-12), declares Laravel 7+ and PHP >= 7.2.5, and will not receive a Nova 4/5 compatibility release. Pin it permanently and treat that constraint as a decision, not a delay:

composer require tightenco/nova-releases:^1.0

1. Read src/ before registering anything. The README and CHANGELOG are thin. Open the service provider and the tool/card class so you know the exact class name, whether it ships as a Tool or Card, and which views/config it publishes. Do not infer this from blog posts — the public docs are the weakest part of this package.

2. Register it in app/Providers/NovaServiceProvider.php. Verify the class name against src/ first:

   public function tools()
   {
       return [
           new \Tighten\NovaReleases\NovaReleases,
       ];
   }
   

   If it registers as a card, add it to cards() instead (or to dashboards() to keep it off the main dashboard).

3. Publish and review config and assets.

   php artisan vendor:publish --provider="Tighten\NovaReleases\NovaReleasesServiceProvider"
   php artisan nova:publish
   

   Open every published key by hand. The config is where you point at your GitHub repository (owner/repo) or a local changelog file path. Set a real source on day one — an empty or misconfigured source renders as a blank card, which is indistinguishable from a broken install.

4. First use case: an internal changelog panel behind a Nova permission gate. Engineers and support/success staff get a read-only answer to "what shipped last deploy?" with no customer-facing surface. It is the highest-value, lowest-risk deployment of this package.

Sanity check: load the Nova dashboard, open the tool, confirm releases render as formatted markdown, and confirm the list populates against your source. A blank card is almost always registration, assets, or source config — see Gotchas.

Implementation Patterns

Cache the GitHub fetch aggressively and test it. The v1.0.0 swap to Illuminate\Support\Facades\Http is the genuinely useful inheritance: you can wrap the fetch in your own cache and test without hitting the network. Unauthenticated GitHub API calls are rate-limited to 60/hour per IP — a shared staging egress plus a few curious admins exhausts that in an afternoon.

$releases = Cache::remember(
    'nova-releases:'.config('nova-releases.repository'),
    now()->addHour(),
    fn () => Http::withToken(config('services.github.token'))
        ->get("https://api.github.com/repos/{$owner}/{$repo}/releases")
        ->throw()
        ->json()
);

Keep the token in config/services.php, never in the package config, and cache for at least an hour. If the package's internal fetch can't be wrapped, warm the cache from a scheduled command and let the card read the warmed value.

Use a local changelog file for repos without a GitHub releases feed. Point the source at base_path('CHANGELOG.md') for monorepos, private repos without a release process, or hand-versioned projects. You own the formatting discipline — keep headings consistent (## [1.4.0] - 2026-01-12) or the parser produces one unhelpful blob.

Gate visibility with Nova's permission model. Don't rely on obscurity if customers or partners share the Nova panel:

public function tools()
{
    return [
        (new \Tighten\NovaReleases\NovaReleases)->canSee(
            fn ($request) => $request->user()?->can('viewReleaseNotes')
        ),
    ];
}

If the class doesn't expose a fluent canSee, wrap registration in a conditional or fork the class — hiding it from non-engineers is non-negotiable.

Treat the "What's new" modal as per-user read state, not a broadcast. Somewhere there is persistence (migration, pivot, or JSON column) tracking which releases each user has seen. Read that migration before running it in production: you're adding schema for a cosmetic feature that will be orphaned when you replace the package. If you fork, prefix the table (nova_release_reads) so the eventual cleanup is a straight drop.

Write Http::fake() tests before forking or upgrading. They are your only regression net for a package nobody else depends on:

Http::fake([
    'api.github.com/repos/*/releases' => Http::response([
        ['tag_name' => 'v1.4.0', 'body' => "## Added\n- thing", 'published_at' => now()->toIso8601String()],
    ], 200),
]);

$this->actingAs($admin)->get('/nova/nova-releases')->assertOk()->assertSee('v1.4.0');
Http::assertSent(fn ($request) => str_contains($request->url(), 'releases'));

Override views and config rather than editing vendor. Publish views into resources/views/vendor/nova-releases/ and adjust to match your theme. That keeps the eventual composer remove to a two-directory cleanup.

Fork only if you must, and fork whole. At 20 stars and zero dependents, adopt-and-own is worse than reimplement. If you do fork: rename the namespace, vendor the source into packages/, scrub any residual Kitetail/Zttp assumptions from tests and lockfiles, and register it with an owner and a review date — treat it as an in-house product with an upstream spec.

Gotchas and Tips

The archive status makes every gotcha below permanent. No security patches, no Nova compatibility fixes, no issue triage. The most likely failure is a silent blank card after a Nova upgrade with no stack trace and no upstream fix. Book a build-vs-fork decision before the next Nova major bump, not after the card goes white.

Re-derive constraints from source, not the docs. Verify the Laravel/PHP floor, the supported Nova major, and the real class names against src/ and composer.lock before putting an estimate in a plan. The release notes describe a transport swap, but they are not a compatibility guarantee.

Blank card: debug in this order. (1) Is the tool in tools() and did you clear the config cache? (2) Did nova:publish compile the front-end assets — the most common silent failure on newer Nova majors. (3) Is the configured source returning data? Curl the GitHub endpoint and check rate-limit headers. (4) Is the class name in NovaServiceProvider correct? Thin docs make typos likely.

config:cache will bite you. Once production config is cached, changing the repository or source path in .env does nothing until php artisan config:cache is re-run. Put that refresh command in the runbook next to "where the release source lives" — those are the two facts on-call needs.

Sanitize rendered markdown. Release bodies come from GitHub or a file and render as HTML inside an authenticated admin page. That is a realistic XSS vector if the source is ever less trusted than your own repo. If you can't verify the package sanitizes, wrap the renderer or configure a strict markdown driver that strips raw HTML. It's the one supply-chain-adjacent risk in an otherwise cosmetic package.

Rate limits and outages are user-visible. With 60 req/hour unauthenticated and no backoff, a rate-limited call renders as "no releases" — which reads as "nothing shipped" rather than "we couldn't reach GitHub." Cache hard, log fetch failures, and distinguish the error empty-state from the genuinely-empty state. The card's whole purpose is telling people what shipped; a stale timeline erodes trust in the panel, not just the card.

Keep it off the release critical path. Read-only, admin-only, low-QPS: warm the fetch on a schedule and never let it fail a deploy. Keep a one-page runbook (source location, cache-refresh command, owner) with the engineer who has read the source. Knowledge concentration is the real operational risk — 20 stars and zero dependents means no community to fall back on.

Prefer these four extension points over patching: publish views, publish and edit config, wrap the fetch in a cached service, and gate visibility in NovaServiceProvider. They cover ~90% of what you'll want to change and survive a composer remove cleanly when you eventually replace the package with your own Nova card.