Laravel Gitscrum Laravel Package

Getting Started

GitScrum is not a library you require into an existing Laravel app — it is a Laravel application (Laravel 5.4/5.5-era). Even though it ships on Packagist as renatomarinho/laravel-gitscrum, the intended workflow is composer create-project or a git clone, then run it as its own self-hosted Scrum board. Plan for it as a separate deployment alongside your real product, not as a package inside it.

Release 1.1.0 does not change this. The changelog is feature/maintenance work (label filters, AJAX issue creation, sync tweaks, a sprint privacy fix, Laravel Page Speed, test/seeder config) — no framework or PHP version bump. Before you start, re-read composer.json and the README in the tag you are installing; that file, not the changelog, tells you the real runtime. Default assumption remains PHP 7.0–7.2, MySQL 5.6/5.7.

Minimal bring-up:

composer create-project renatomarinho/laravel-gitscrum gitscrum --prefer-dist
cd gitscrum
cp .env.example .env
php artisan key:generate
# edit .env: DB_*, APP_URL, MAIL_*, GITHUB_CLIENT_ID/SECRET/CALLBACK_URL
php artisan migrate
php artisan db:seed
php artisan serve

Where to look first, in order:

routes/web.php — the whole surface area is a handful of resource routes (projects, sprints, user stories, tasks, issues). 1.1.0 added AJAX endpoints for issue creation, so check this file rather than trusting older route lists.
app/Http/Controllers/ — board logic plus GitHub/Bitbucket/GitLab sync. IssueController was refactored in 1.1.0, so any local patch you carried there needs re-applying.
.env + config/gitscrum.php / config/services.php — OAuth credentials, integration toggles, and whatever knobs Laravel Page Speed introduced.
database/migrations/ — the actual domain model; read these before writing any report or query (including the new seeder/test config).
resources/views/ — Blade templates you will end up editing because there is no real theming layer.

First use case that proves the tool out: create a project → connect a GitHub repo via OAuth → create a sprint (test a private one — 1.1.0 claims to fix private-sprint mode) → populate user stories from the backlog → tag a couple with labels → drag them across the board → create an issue from the board via the new AJAX form. If OAuth round-trip, label filtering, and commit/issue sync all work, the rest of the app is just CRUD.

Implementation Patterns

Run it as a satellite app. Deploy it on its own subdomain (e.g. scrum.internal.example.com) behind your SSO or basic auth. Treat its database as a separate schema. This keeps the 2017 dependency tree away from anything customer-facing.

Repo integration is the whole point — set it up deliberately. Register a GitHub OAuth app with a callback that exactly matches APP_URL + the route GitScrum expects. Then add the webhook for the repo so commits and issues flow in. Typical day-to-day loop:

Issues/commits arrive via webhook → appear against user stories.
1.1.0's "sync without detach" means a re-sync should no longer orphan issues from their user stories. Verify on a throwaway project before re-syncing real ones, and check for duplicate issue rows afterwards.
Sprint planning pulls backlog stories into the active sprint.
Use labels as your primary cross-cutting taxonomy. The new user-story label filter is the cheapest way to carve the board (client, epic, tech-debt, on-call) without a schema change or a fork patch. Prefer it over a custom field until you outgrow it.
Issue creation from the board is now AJAX-driven, which is faster for standups but means errors surface in the browser console rather than a full page reload — check storage/logs/laravel.log when the modal "does nothing".
Standup is the activity feed + board columns, not a separate doc.
Velocity is whatever the sprint/board views compute — verify the numbers against the raw tables before you quote them upward.

Team and permissions setup early. Roles are project-scoped; get the project owner and member assignments right before inviting people, because re-parenting users later is manual DB work. The 1.1.0 private-sprint fix is worth re-testing with a non-owner account: confirm a private sprint is actually invisible/read-only server-side, not merely hidden in the UI.

Extend by owning the fork, not by hoping for hooks. Because you have the full app source, the practical extension patterns are:

New migration + model + resource route for any custom field (story points, client, epic).
Override Blade views in resources/views/ directly (no publish tags to lean on). Diff your overrides against upstream on every version bump — 1.1.0 touched controllers and likely views.
Add your own Artisan command under app/Console/Commands for exports, nightly velocity snapshots, or Slack digests; wire it into app/Console/Kernel.php.
Add a middleware for SSO/IP allowlisting rather than trusting the built-in auth.
Listen to Eloquent events (UserStory::updated, etc.) to push notifications out to Slack/Teams instead of polling.
Write tests now. 1.1.0 ships test configuration and seeders. That is the single most useful thing in the release: it lets you pin behaviour (label filter, sync-without-detach, sprint privacy) before you start patching, so upgrades become a diff-and-run instead of manual QA.

Ops pattern:

Cron: * * * * * php artisan schedule:run.
A queue worker only if the repo sync is queued in your version — check config/queue.php and the sync controllers before assuming.
Nightly mysqldump of the GitScrum schema; it is the only copy of your sprint history.
APP_DEBUG=false and a real APP_URL in production, permanently.
Review the new Laravel Page Speed config: keep it off in local/staging so it doesn't confuse debugging, and be ready to disable it if it mangles responses.

Fork-and-pin strategy for maintenance. Commit the composer.lock, pin the PHP version in a Docker image, and never run composer update casually. Upgrading to 1.1.0 is a cherry-pick/rebase onto your fork: pull the release, re-apply local view and controller patches, run your new test suite, then re-run the private-sprint and re-sync checks before touching production data.

Gotchas and Tips

The biggest trap: treating it as a package. composer require renatomarinho/laravel-gitscrum in your existing app gives you a second Laravel application's source tree, conflicting service providers, conflicting migrations, and no clean integration seam. Don't.
"Effectively abandoned" needs qualifying. Last release was 2017-10-01; 1.1.0 shows upstream is alive again, but the underlying Laravel/Symfony/Guzzle tree was not rebased. Treat it as a maintained-ish app on a frozen runtime: you can expect small feature and bugfix patches, not security or framework upgrades. Laravel 9/10 and PHP 8 remain out of scope.
Dependency CVEs. The 2017 Laravel/Symfony/Guzzle set has known issues. Never expose it to the public internet without an auth proxy in front.
Default seeded admin. db:seed creates an admin account with known credentials — change the password and the email immediately, or don't seed in production. 1.1.0 reworked seeders, so re-check what db:seed inserts rather than assuming it's unchanged.
MySQL 8 / MariaDB strict mode will reject some of the old migrations (TIMESTAMP defaults, index lengths, implicit utf8mb4 conversions). Workaround: run migrations with a relaxed sql_mode, or patch the migrations. Do this before you have data.
Asset build is the second-most-common failure. The bundled Node/Bower/Gulp toolchain predates modern Node. Use an old Node in Docker, or vendor the compiled public/ assets once and never rebuild. Note that 1.1.0's AJAX issue creation may include JS changes — check whether public/ needs a rebuild or whether compiled assets were committed.
Laravel Page Speed middleware is a debugging hazard. It minifies/inlines responses; if the board or AJAX issue modal starts behaving oddly after upgrade, disable it first and re-test before touching anything else.
OAuth callback mismatches are almost always APP_URL vs. the real scheme/host, or a proxy stripping X-Forwarded-Proto. Set TrustProxies and a correct APP_URL before debugging the provider.
Webhook route and CSRF. If the provider's POST gets a 419, the webhook route is inside the web middleware group. Exclude it in VerifyCsrfToken (and verify the payload signature yourself, since the built-in check is dated).
After upgrading to 1.1.0, specifically re-test: label filtering on large boards (N+1 query risk), the AJAX issue-create path (validation errors, auth, CSRF), a re-sync of an already-synced repo (duplicates / detached issues), and private sprints with a restricted user.
No reliable public API. Don't build integrations against an assumed REST surface — check routes/ first. If you need one, add it: a small API controller reading the same Eloquent models is cheaper than scraping the HTML.
Debugging playbook: storage/logs/laravel.log, php artisan route:list | grep, php artisan tinker to inspect projects, sprints, user_stories, tasks, labels directly. Most "the board is wrong" reports are a status enum value that no view accounts for.
Exit strategy. It's plain Laravel + MySQL, so your data is portable. If you migrate to Jira/Linear/GitHub Projects later, write a one-off Artisan export command from the Eloquent models — do that early, while the schema is still the one you understand.