Cli Laravel Package

Technical Evaluation

Architecture fit

• Shipper is a deployment/orchestration CLI targeting Laravel/PHP applications. It sits outside the application runtime — it is not a Composer library you require into vendor/, so it does not couple to our application architecture, service container, or framework version. That is a positive for fit: adoption is additive and reversible.
• The v1.0.3 change ("Expose the Composer CLI binary", PR #103) converts distribution from a Composer-installed binary to a standalone, downloadable executable. This matters architecturally: it decouples the deploy tool from the application's composer.json/lockfile, which means we can version and upgrade the deploy tool independently of the app.
• Remaining architectural question: whether the CLI expects to own the release/deploy lifecycle end-to-end (build, release directory, symlink switch) or can be run alongside an existing pipeline as a step. This determines whether it is a replacement architecture or an additive one.

Integration feasibility

• Low-friction path: download artifact, chmod +x, ./shipper --version, then invoke from CI. No PHP extension or Composer plugin dependency surface introduced by this release — a net reduction in integration complexity versus the v1.0.2 Composer-binary route.
• Verification is feasible and cheap: the release publishes a SHA-256 checksum and GitHub build provenance, so checksum + gh attestation verify can be wired into CI as a gate before execution.
• Blocking unknown: the README is cited but not included in these notes. We cannot yet confirm required credentials/secrets (SSH keys, deploy tokens), target-host prerequisites, or whether it supports our specific hosting topology (managed PaaS vs. bare VM vs. container).

Technical risk

• Medium — supply chain. A downloaded, self-executing binary entering CI and production hosts is a higher-trust surface than a pinned Composer package. Mitigated, not eliminated, by checksums + provenance. We must confirm provenance is generated by a GitHub Actions workflow in the shippercli/cli repo and that we pin by digest, not by the mutable v1.0.3 tag.
• Low — breaking change. Patch-level release; semantic signal is "no breaking API change". Risk is confined to distribution mechanics.
• Medium — binary portability. Standalone binaries imply per-OS/per-arch artifacts (Linux/macOS, amd64/arm64). Release notes do not enumerate the matrix; an unsupported CI runner arch (e.g., arm64 runners, Alpine/musl) would silently block adoption.
• Low — vendor maturity. Single-maintainer project (@marktopper); small bus factor. This is the dominant long-term risk, not the code itself.

Key questions

1. Is the binary a single universal artifact, or a per-platform matrix? Which OS/arch combinations are published and attested?
2. Is provenance an SLSA-style attestation verifiable offline/with gh attestation verify, and are we expected to pin by digest?
3. Does the CLI require root/elevated privileges on target hosts, or can it run as the deploy user?
4. Does it assume it owns the release directory and current symlink, or can it be scoped to a single pipeline stage?
5. What is the support/response posture for a single-maintainer project, and is there a fallback (pin to v1.0.2's Composer binary) if v1.0.3 proves unusable?
6. Does the CLI phone home, and what data leaves our network?

Integration Approach

Stack fit

• Fits a Laravel/PHP stack as a pipeline-layer tool, not an application dependency. It does not appear in composer.json, does not affect autoloading, and does not raise the PHP version floor for the app.
• Natural home: a dedicated CI job (or a container image layer) that provisions the binary once and runs the deploy step. This keeps the binary out of application images and out of developer laptops on day one.

Migration path

• Since there is no prior assessment and no incumbent Shipper adoption, this is a greenfield pilot, not a migration. Recommended: pin v1.0.3 in a single non-production environment, verify checksum + provenance, and measure whether the CLI's deployment model matches our current process.
• Explicit fallback: v1.0.2 remains available via the Composer binary channel. If the standalone binary is unavailable for our runner architecture, we can either (a) pin v1.0.2, or (b) build from source. Document this before the pilot closes.
• If adopted, retire any existing hand-rolled deploy scripting only after a parallel-run period where both pipelines can produce a release.

Compatibility

• Verify: runner OS/arch coverage (Linux glibc, musl/Alpine, arm64); whether the binary is statically linked; minimum glibc if not.
• Verify: interaction with our PHP version matrix — as an external binary it should be PHP-agnostic, but if it shells out to composer/php on the target host, our target PHP versions become a compatibility input.
• Verify: behavior on Laravel versions we currently support, if the CLI performs app-level operations (migrations, cache clearing) rather than pure file/symlink operations.

Sequencing

1. Validate artifact — download in an isolated CI job; confirm SHA-256 match and successful provenance verification; record the pinned digest.
2. Discover requirements — ./shipper --version, then --help; enumerate commands, config file format, and required secrets. Close the README gap.
3. Pilot on staging — one non-production app, one deploy path, checksum-gated. Capture logs and rollback behavior.
4. Parallel run in production-adjacent environment versus the existing deploy mechanism.
5. Production cutover for one service, digest-pinned and checksum-gated in CI.
6. Standardize — publish an internal runbook and an org-wide pinned version before broadening beyond a second service.

Operational Impact

Maintenance

• Upgrades are now a binary-swap-and-repin exercise rather than a composer update. This is less entangled with application dependency maintenance and avoids the classic Laravel pain of a deploy tool pinning transitive Composer packages.
• Cost shifts to us: we now own pinning, digest tracking, and monitoring upstream releases. Budget a recurring per-release review task — this is a patch release, so cadence is likely frequent.
• Single-maintainer upstream means we should be prepared to vendor or fork the binary if the project stalls.

Support

• No commercial support expected. Support model is GitHub issues plus README. For a deploy-path tool, that is a real gap: deploy failures are high-urgency by definition.
• Mitigation: keep the previous deployment mechanism documented and executable for at least one quarter post-adoption so we are never blocked on upstream responsiveness.
• Internally, designate one owner for the deploy toolchain so artifact verification and version decisions have an accountable party.

Scaling

• Scales fine along the application axis — a per-pipeline binary is cheap and the deploy step is short-lived.
• Watch the fan-out axis: N services × M environments means N×M places pinning the digest. Centralize by baking the verified binary into a shared CI base image or internal artifact mirror, so version bumps are one change, not many.
• Provenance/checksum verification adds seconds per job; negligible, but caching the binary in an internal mirror keeps runner egress off GitHub on every build.

Failure modes

• Unverified/absent artifact on CI runner (arch mismatch, GitHub outage, rate limiting) → deploy job fails or, worse, runs an unverified binary if the gate is skippable. Gate must be fail-closed and the binary must be sourced from an internal mirror.
• Checksum/provenance mismatch → treat as a security incident path, not a retry. Block the pipeline and alert.
• Tag mutability → pinning to v1.0.3 rather than a digest is the highest-likelihood silent failure; enforce digest pinning in the pipeline template.
• Upstream abandonment / compromised release → fallback to v1.0.2 Composer binary or a locally built artifact.
• Deploy-model mismatch (CLI assumes symlink ownership on a host where another process owns it) → partial deploys. Surfaces in the staging pilot; do not discover it in production.
• Missing rollback path → confirm the CLI's failure behavior mid-deploy before cutover; a deploy tool that fails open is disqualifying.

Ramp-up

• Engineer time: low-to-moderate — an afternoon to validate the artifact and enumerate CLI surface, 1–2 days for a staging pilot, plus parallel-run overhead.
• TPM time: moderate — closing the README/documentation gap, chasing arch coverage and provenance confirmation upstream, and socializing the digest-pinning policy with the platform/CI owners.
• Decision gate for production: artifact verified (checksum + provenance), runner arch confirmed, required secrets identified, rollback validated, and a documented fallback to v1.0.2. If any of these are unmet, hold at pilot and continue on the existing deploy mechanism — the release is a patch-level distribution change and carries no forcing function to adopt this quarter.