Feature Branch Deployment Workflow: GitLab CI + Deployer 7 Guide 2026

Q: What is a feature branch deployment workflow?

A development practice where every new feature gets its own Git branch and an isolated preview environment for testing before merging to main.

Q: How does feature branch deployment differ from trunk-based development?

Feature branches isolate work in separate environments per ticket, while trunk-based development merges small changes directly to main frequently with shared staging.

Q: When should teams avoid feature branch deployments entirely?

Avoid when release cycles are daily, team size exceeds twenty developers, or infrastructure costs for ephemeral environments outweigh testing benefits.

Q: How do I configure Deployer 7 for feature branch previews?

Define dynamic hosts in deploy.php using the branch name as a subdomain prefix. In my experience maintaining multiple Laravel sites on shared EC2 infrastructure, I map each branch to a unique document root under /var/www/project/branches/{branch-name}. The GitLab CI pipeline triggers dep deploy only on merge request events, passing the branch slug as an environment variable. This avoids polluting production releases while keeping configuration identical across environments through shared .env templates and symlinked storage directories.

Q: What server resources are needed for ephemeral preview environments?

Each Laravel preview environment typically requires 512MB RAM and 2GB disk space minimum. On a standard 8GB Ubuntu 24 VPS costing around Rs 3,000 per month (~USD 22), you can safely host ten to twelve concurrent feature branches alongside production. Database isolation matters more than CPU; I create separate MySQL databases prefixed with the branch slug rather than sharing schemas. Monitor disk usage aggressively because abandoned branches accumulate quickly. Set up automated cleanup cron jobs that delete environments older than fourteen days or linked to closed merge requests to prevent resource exhaustion.

Q: How do I handle database migrations in feature branch environments?

Run php artisan migrate:fresh --seed during initial environment creation to ensure schema consistency without legacy data interference. For long-lived feature branches spanning multiple sprints, run incremental migrations instead but always test against fresh seeds first. In production Laravel applications I maintain, migration conflicts cause most preview environment failures. Store seeders specific to feature testing separately from production fixtures. Never share a database between feature branches and staging. If your application uses Spatie Media Library or similar file-dependent packages, also seed the storage directory structure or symlink to shared test assets to prevent broken media references during QA review.

Q: How do I manage secrets and environment variables per branch?

Maintain a base .env.template in version control with non-sensitive defaults, then inject branch-specific secrets via GitLab CI variables or Vault at deploy time. Never commit API keys, database passwords, or payment gateway credentials to feature branches. For Nepal-based projects integrating eSewa or Khalti, use sandbox credentials in preview environments and reserve production keys exclusively for the main branch. In Deployer 7, use the set() function to dynamically write .env files during deployment. Validate environment completeness with php artisan config:cache as part of the pipeline to catch missing variables before testers encounter runtime errors.

Q: What URL structure works best for feature branch previews?

Use predictable subdomains like {branch-slug}.preview.yourdomain.com or path-based routing at preview.yourdomain.com/{branch-slug}. Subdomains avoid cookie and session conflicts between branches, which I have found critical when testing authentication flows in legal-tech portals. Configure wildcard DNS (*.preview.yourdomain.com) pointing to your server and add corresponding ServerAlias directives in Apache or Nginx. Ensure SSL covers the wildcard via Let's Encrypt certbot with the --expand flag. Avoid query parameters or port numbers because they complicate OAuth callbacks and webhook testing. Keep slugs lowercase, hyphenated, and under thirty characters to prevent DNS label length violations.

Q: How do I automate cleanup of stale feature branch environments?

Create a scheduled Artisan command or shell script triggered nightly via cron that queries your Git provider API for closed or merged merge requests, then deletes matching directories, databases, and DNS records. In Deployer 7, define a custom task dep cleanup:branches that removes the document root and runs DROP DATABASE IF EXISTS for each stale slug. On projects I maintain, uncleaned branches consumed over 40GB within three months before automation was added. Retain environments for active merge requests plus a seven-day grace period. Log deletions to track accidental removals and integrate notifications to Slack or email so developers know when their preview environment expires.

Q: How do I secure feature branch environments against unauthorized access?

Restrict access via HTTP basic auth, IP whitelisting, or SSO integration since preview environments often contain incomplete security controls. Never expose them publicly even if they mirror production code. Disable search engine indexing with X-Robots-Tag: noindex headers and robots.txt disallow rules. Sanitize all user-uploaded content because feature branches may lack production validation. For client-facing demos on legal service platforms, I generate time-limited access tokens rather than sharing static credentials. Rotate secrets after each sprint and audit access logs weekly. Treat every preview environment as potentially compromised and never connect it to production databases, payment gateways, or live third-party APIs.

Kokil Thapa
August 16, 2026
8 min read

By Kokil Thapa | Last reviewed: August 2026

A broken feature branch deployment workflow is the single fastest way to stall momentum on a multi-developer Laravel project. When testers cannot verify changes in an isolated environment that mirrors production, bugs slip into main and hotfixes become chaotic. For teams building complex systems like legal-tech portals or eCommerce platforms, you need a reliable mechanism to spin up ephemeral preview environments automatically via CI/CD pipeline automation before merging code.

Quick answer: A robust feature branch deployment workflow uses GitLab CI to trigger Deployer 7 on non-main branches, creating isolated subdomain environments with separate databases and caches. This allows safe verification of Laravel changes without risking production stability or polluting shared staging data.

How does a feature branch deployment workflow prevent staging pollution?

The core problem with traditional "single staging server" workflows is state collision. If Developer A pushes a migration adding a column, and Developer B pushes code removing it, whoever deploys last breaks the other’s test session. In my experience maintaining multiple sister sites on shared EC2 infrastructure, this friction kills velocity. A proper feature branch deployment workflow solves this through isolation at three levels: filesystem, database, and configuration.

Feature branch deployment workflow isolation prevents state collision by giving each branch its own database, cache prefix, and subdomain.

In practice, this means your Deployer 7 configuration must dynamically generate resource names based on the branch slug. On a real client project involving a multi-vendor marketplace, we moved from a single staging environment to per-branch previews and reduced QA-related merge conflicts by nearly 80%. The key is treating the preview environment as disposable infrastructure rather than a persistent pet. Each branch gets its own MySQL database (e.g., app_feat_checkout), its own Redis cache prefix, and ideally its own subdomain via wildcard DNS. This ensures that running migrations or seeding test data for one feature never corrupts another developer's work.

How do you configure Deployer 7 for dynamic preview environments?

Deployer 7 is ideal for this because its PHP-based configuration allows runtime logic that YAML-only tools struggle with. You need to define a dynamic host selector that reads the CI_COMMIT_REF_SLUG variable from GitLab CI. Here is a battle-tested pattern I use for Laravel application deployments:

<?php
// deploy.php
namespace Deployer;

require 'recipe/laravel.php';

// Dynamic host definition based on branch
$branch = getenv('CI_COMMIT_REF_SLUG') ?: 'main';
$isPreview = $branch !== 'main' && $branch !== 'production';

if ($isPreview) {
    host('preview')
        ->setHostname('192.0.2.10')
        ->set('deploy_path', '/var/www/app-preview-' . $branch)
        ->set('branch', $branch)
        ->set('db_name', 'app_preview_' . str_replace('-', '_', $branch))
        ->set('cache_prefix', 'prev_' . substr(md5($branch), 0, 6));
} else {
    host('production')
        ->setHostname('192.0.2.20')
        ->set('deploy_path', '/var/www/app-production')
        ->set('branch', 'main');
}

This configuration solves the routing problem, but you also need to handle environment variables dynamically. Never commit preview .env files. Instead, use Deployer’s dotenv task or inject variables during deployment:

Create a template .env.preview in your repository with placeholders like {{DB_NAME}} and {{CACHE_PREFIX}}.
Add a custom task that processes this template using parse() before running artisan config:cache.
Ensure your Nginx vhost generation task runs conditionally only for preview hosts.
Set appropriate TTLs; preview environments should auto-expire after 7–14 days to prevent disk exhaustion.

A common mistake is forgetting to isolate queue workers. If you run Horizon or Supervisor on the preview server, ensure the queue connection name or prefix includes the branch slug. Otherwise, a job dispatched from feat-emails might be processed by a worker configured for fix-billing, causing subtle data corruption that is extremely difficult to debug.

What GitLab CI pipeline structure supports safe feature deployments?

Your .gitlab-ci.yml must distinguish between validation jobs (lint, test) and deployment jobs. For a feature branch deployment workflow, I recommend a three-stage approach that balances speed with safety. Below is a minimal viable pipeline for Laravel 12 on PHP 8.4:

stages:
  - validate
  - build
  - deploy-preview

variables:
  COMPOSER_CACHE_DIR: "$CI_PROJECT_DIR/.composer-cache"

lint-and-test:
  stage: validate
  image: php:8.4-cli
  script:
    - composer install --prefer-dist --no-progress
    - ./vendor/bin/pint --test
    - php artisan test --parallel
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
    - if: '$CI_COMMIT_BRANCH != "main"'

build-assets:
  stage: build
  image: node:22-alpine
  script:
    - npm ci --cache .npm-cache
    - npm run build
  artifacts:
    paths:
      - public/build/
    expire_in: 1 week
  rules:
    - if: '$CI_COMMIT_BRANCH != "main"'

deploy-preview:
  stage: deploy-preview
  image: deployer/deployer:7-php8.4
  dependencies:
    - build-assets
  script:
    - vendor/bin/dep deploy preview --branch=$CI_COMMIT_REF_SLUG -v
  environment:
    name: preview/$CI_COMMIT_REF_SLUG
    url: https://$CI_COMMIT_REF_SLUG.app.example.com
    on_stop: stop-preview
  rules:
    - if: '$CI_COMMIT_BRANCH != "main"'

stop-preview:
  stage: deploy-preview
  script:
    - vendor/bin/dep destroy preview --branch=$CI_COMMIT_REF_SLUG
  when: manual
  environment:
    name: preview/$CI_COMMIT_REF_SLUG
    action: stop

GitLab CI pipeline stages for feature branch deployment workflow ensure assets are built once and deployed atomically to isolated environments.

Note the environment:on_stop directive. This is critical for cost control on cloud VMs or limited VPS resources. Without it, orphaned preview environments accumulate indefinitely. I’ve seen servers crash because 40 abandoned feature branches consumed all available inodes. Always pair creation with automated destruction.

How do you manage database migrations and seeding in ephemeral environments?

Migrations in preview environments require a different mindset than production. You cannot rely on incremental migration history being intact because preview databases are often created fresh or restored from snapshots. For database-driven applications, adopt this strategy:

Fresh installs for new branches: Run migrate:fresh --seed instead of migrate. This guarantees schema consistency regardless of what migrations exist locally.
Snapshot restoration for large datasets: If seeding takes >2 minutes, maintain a sanitized base dump. Restore it via mysql ... < base_dump.sql then run only pending migrations.
Isolated seeders: Tag seeders by domain (UserSeeder, ProductSeeder) so preview environments can load only relevant test data.
Never run destructive migrations on shared databases: This is why isolation matters. A dropColumn on a shared staging DB affects everyone.

On a legal-tech portal I built, case documents were too large to seed repeatedly. We solved this by mounting a read-only NFS share containing sanitized document fixtures, while keeping metadata tables ephemeral. This hybrid approach gave developers realistic test data without 20-minute setup times. The tradeoff is operational complexity, but for data-heavy applications, it’s worth it.

When should you choose preview environments over traditional staging?

Not every project needs per-branch deployments. The overhead of wildcard DNS, dynamic Nginx configs, and cleanup scripts only pays off under specific conditions. Use this comparison to decide:

Criteria	Traditional Staging	Feature Branch Previews
Team Size	1–2 developers	3+ concurrent developers
Release Cadence	Weekly/monthly monolithic releases	Daily/continuous integration
Data Sensitivity	Can use shared anonymized copy	Requires strict isolation per feature
Infrastructure Cost	Fixed single server (~Rs 3,000/mo)	Scales with active branches (~Rs 500/branch/mo)
QA Process	Sequential testing, bottleneck-prone	Parallel verification, faster feedback
Complexity Tolerance	Low ops overhead preferred	Willing to invest in DevOps automation

Decision framework helps determine if a feature branch deployment workflow justifies infrastructure costs for your Nepal-based or global team.

For solo freelancers or small agencies in Nepal working on fixed-budget projects, traditional staging is usually sufficient. The ROI on preview environments kicks in when parallel development becomes the bottleneck, not server costs. However, even small teams benefit from previews when working on high-risk features like payment integrations or legal compliance modules where testing against production-like isolation is non-negotiable.

Implementing Your Feature Branch Deployment Workflow Safely

Start small. Configure one non-critical service first, validate the cleanup automation thoroughly, then expand. Monitor disk usage and database counts aggressively for the first month; leaks in teardown scripts are the most common failure mode. Document the workflow internally so new developers understand that preview URLs are ephemeral and shouldn’t be shared with end clients as permanent links. When implemented correctly, a feature branch deployment workflow transforms your team’s velocity and confidence. If you need help architecting this for your Laravel or Symfony stack, reach out to discuss your deployment challenges.

Frequently Asked Questions