Artisan Release Command Laravel Package

Getting Started

Install it as a dev dependency so it never ships in production builds:

composer require --dev michael-rubel/artisan-release-command

Then publish whatever config the package ships with (check the service provider's publishes() call for the exact tag — commonly --tag=release or --tag=artisan-release-command) and open the resulting config/release.php. That file is the first place to look: it defines where the version number lives, which Git operations run, and which commands are executed before/after a release. The second place is vendor/michael-rubel/artisan-release-command/src/ — with 15 stars and no dependents, the source is the documentation.

Confirm the commands registered:

php artisan list release

You should see release:patch, release:minor, and release:major (semver-style bumps, npm-version-like).

First use case: a clean main branch, a green test suite, then:

git status                 # must be clean
php artisan release:patch  # bumps version, commits, tags
git push --follow-tags     # publish the tag

If that produces a version-bump commit and an annotated tag, the package is doing its job. If not, read the config — the release flow is entirely driven by it.

Implementation Patterns

Treat the config as your release script. The value of this package is the hook list. A realistic config/release.php shape:

return [
    'before' => [
        'test',
        'phpstan',
        'npm run build',
    ],
    'after' => [
        'changelog:generate',   // if you use one
    ],
    // plus whatever file/path the version is written to
];

Anything you'd otherwise type by hand after tagging belongs in before or after. This is the difference between "a version bumper" and "a release process."

Single source of truth for the version. Point the config at one file (config/app.php, a version file, or a VERSION constant) and read it everywhere else — a Version::current() helper, your /health endpoint, Sentry's release option, a footer in your admin panel. Nothing is worse than a tag saying v2.3.1 while the app reports 2.2.0.

CI release job. Run it from a dedicated workflow triggered on merge to main, never from a developer laptop:

- run: git config user.name "release-bot"
- run: git config user.email "[email protected]"
- run: php artisan release:patch --no-interaction
- run: git push --follow-tags

Set the remote with a token, not interactive credentials:

git remote set-url origin "https://x-access-token:${GIT_TOKEN}@github.com/org/repo.git"

Tag your deployables from the same version. After the bump, read the version file in the next step and use it for the Docker image tag, the Sentry release, or the deploy marker. That keeps artifact, tag, and error tracking aligned.

Branch strategy. Release only from main. Hotfixes are the one case where you tag from a hotfix/* branch — but then cherry-pick the version bump back to main so the next release doesn't collide.

Pair it with a changelog tool, not instead of one. This package bumps and tags; it does not curate release notes. Conventional commits + git-cliff / changelog:generate in the after hook is the usual combination.

Gotchas and Tips

• Dirty tree is the #1 failure. Commit or stash before running. A release that tags a half-finished working directory is a mess to untangle.
• Unpushed commits. The tag points at HEAD; if HEAD isn't on the remote, the tag is orphaned for everyone else. Push the branch first, or make git push part of the flow.
• Branch protection. A bot pushing a version-bump commit straight to main will be rejected unless the ruleset exempts the bot or allows it to bypass. Plan for this before the first CI run, or the release job fails after it has already tagged locally.
• Partial failures leave residue. If a before hook fails after the version file was written, or a commit succeeds but the tag push fails, you get a half-released state. Read the package source to know the exact ordering (bump → hook → commit → tag, or some variant) so you know what to undo. Recovery is usually git tag -d vX.Y.Z, git reset --hard HEAD~1.
• Non-interactive mode. Use --no-interaction in CI; any confirmation prompt will hang the runner. Also verify it doesn't prompt for a version string when you intended a semver bump.
• Git identity on CI. Runners have no user.name/user.email; the commit step fails with a cryptic message. Set them explicitly.
• config:cache staleness. On deploy machines, php artisan config:cache before the release means your hook edits aren't picked up. Clear config cache around release steps.
• Pre-release versions. Check whether 1.2.3-beta.1 style tags are supported by the bump logic before relying on them; if not, keep pre-releases manual.
• Coexistence. Don't run this alongside release-it, semantic-release, or npm's version in the same repo — they'll each try to own the tag and version file.
• Maintenance risk. 15 stars, zero dependents, last release Nov 2024. Pin the version in composer.json, read the source before upgrading, and be prepared to fork. It's a thin wrapper over Git + Symfony Process, so forking or replacing with a dozen lines of your own Artisan command is a realistic fallback if it stalls on a future Laravel version.