Comparing Deployments via Shell Scripts vs. Deployer vs. Ansible in GitLab

1. The starting point: three tools, one task

Anyone setting up a deploy job for Magento in GitLab CI/CD faces a fundamental decision: which tool actually carries out the deployment process on the target server? Three approaches dominate in practice: shell scripts, which run directly in the script block of the .gitlab-ci.yml or as separate Bash files. Deployer PHP, a specialized deployment tool with a built-in release model, rollback functionality and a library of recipes for popular frameworks. And Ansible, an agentless configuration management tool that describes infrastructure and deployment through YAML playbooks.

All three approaches can technically deliver the same result: an updated Magento instance on the production server. But they differ significantly in maintainability, scalability, learning curve and how they handle errors. Choosing the wrong tool leads either to deployment scripts nobody wants to touch anymore, or to an infrastructure complexity that is oversized for the actual problem.

This article compares all three approaches with concrete examples, shows how they integrate into GitLab pipelines, and provides a clear decision matrix for different team and project sizes. The focus is on Magento-specific requirements, in other words everything that goes beyond a simple file transfer.

2. Deployment via shell scripts: simple, direct, but limited

Shell scripts are the easiest way into automated deployments. They need no additional tools, no configuration files beyond the .gitlab-ci.yml, and no specialized know-how. A deploy job built on Bash runs rsync, connects to the server over SSH and executes Magento commands. This works well for single servers and simple deployment patterns.

The limits of shell scripts show up once release management, rollback or multi-server deployments come into play. Anyone implementing release directories, symlink switching and shared paths manually in Bash quickly ends up with a hundred lines of code that are hard to read, barely testable and difficult for other developers to change without ramp-up time. The effort required for error handling grows proportionally with complexity, and Bash error handling is notoriously tricky.

# Shell-based deploy job, simple but grows complex fast
deploy:shell:
  stage: deploy
  image: debian:bookworm-slim
  before_script:
    - apt-get update -qq && apt-get install -y -qq openssh-client rsync
    - eval $(ssh-agent -s)
    - echo "$SSH_PRIVATE_KEY" | tr -d '\r' | ssh-add -
    - mkdir -p ~/.ssh && echo "$SSH_KNOWN_HOSTS" > ~/.ssh/known_hosts
  script:
    # Create timestamped release directory
    - RELEASE=$(date +%Y%m%d-%H%M%S)
    - ssh "$DEPLOY_USER@$DEPLOY_HOST" "mkdir -p $DEPLOY_PATH/releases/$RELEASE"
    # Sync build artifact to new release directory
    - rsync -az --delete ./ "$DEPLOY_USER@$DEPLOY_HOST:$DEPLOY_PATH/releases/$RELEASE/"
    # Set shared symlinks and switch current
    - |
      ssh "$DEPLOY_USER@$DEPLOY_HOST" "
        ln -sfn $DEPLOY_PATH/shared/app/etc/env.php $DEPLOY_PATH/releases/$RELEASE/app/etc/env.php
        ln -sfn $DEPLOY_PATH/shared/pub/media $DEPLOY_PATH/releases/$RELEASE/pub/media
        cd $DEPLOY_PATH/releases/$RELEASE
        php bin/magento cache:flush
        ln -sfn $DEPLOY_PATH/releases/$RELEASE $DEPLOY_PATH/current
      "

3. Deployer PHP: release structure and rollback as a built-in feature

Deployer PHP solves the problems of shell scripts by bringing release management, shared paths and rollback along as built-in concepts. The configuration in deploy.php is declarative and readable. Deployer already knows what a release structure is, how symlinks need to be set and how a rollback is carried out, so the team does not have to implement this logic itself. On top of that, there are recipes for Magento that predefine commonly needed tasks.

The downside: Deployer is a PHP tool with its own learning curve. Anyone unfamiliar with the Deployer API needs time to understand and adapt the configuration file. Tasks that go beyond the supplied recipes have to be written in PHP. For teams with a strong PHP background that is not an issue. For DevOps engineers without PHP experience, it can be an unfamiliar way of working.

4. Ansible: infrastructure as code for complex environments

Ansible is not a deployment tool in the strict sense, but a configuration management tool that can also be used for deployments. Playbooks describe the desired state of the server, and Ansible brings that state about through idempotent tasks. This makes Ansible particularly strong for environments where deployment and server configuration are closely linked, for instance when every release also needs to adjust PHP extensions, Nginx configuration or cron jobs.

For pure Magento deployments onto already-prepared servers, Ansible is often oversized. The learning curve is steep, playbooks quickly become complex, and the overhead is noticeable for simple deployments. Ansible makes sense for teams that already run configuration management, for multi-environment setups with widely differing server configurations, and for cases where a deployment also changes server state, not just application code.

# Ansible playbook, Magento deploy excerpt
# ansible/deploy.yml
- name: Deploy Magento release
  hosts: production
  vars:
    deploy_path: "{{ lookup('env', 'DEPLOY_PATH') }}"
    release_id: "{{ lookup('pipe', 'date +%Y%m%d-%H%M%S') }}"
    release_path: "{{ deploy_path }}/releases/{{ release_id }}"

  tasks:
    - name: Create release directory
      file:
        path: "{{ release_path }}"
        state: directory
        mode: '0755'

    - name: Sync build artifact via rsync
      synchronize:
        src: "{{ playbook_dir }}/../"
        dest: "{{ release_path }}/"
        delete: yes
        rsync_opts:
          - "--exclude=.git"
          - "--exclude=tests"

    - name: Link shared env.php
      file:
        src: "{{ deploy_path }}/shared/app/etc/env.php"
        dest: "{{ release_path }}/app/etc/env.php"
        state: link

    - name: Switch current symlink atomically
      file:
        src: "{{ release_path }}"
        dest: "{{ deploy_path }}/current"
        state: link

    - name: Flush Magento cache
      command: php bin/magento cache:flush
      args:
        chdir: "{{ release_path }}"

5. Integration into GitLab pipelines: what it looks like

All three tools can be integrated into GitLab pipelines, but the integration looks different for each. Shell scripts live directly in the script block or get checked into the repository as files and run from there. Deployer is installed as a Composer dependency and invoked in the pipeline job via vendor/bin/dep deploy production. Ansible is installed on the runner and invoked via ansible-playbook, with the inventory generated dynamically from CI/CD variables if needed.

The pipeline structure is similar across all three approaches: the build stage produces the artifact, the deploy stage transfers it and runs the server-side steps, and the verify stage checks the result. The difference lies in the readability and maintainability of the deploy step: shell scripts become harder to read as complexity grows, Deployer stays clear thanks to its declarative configuration, and Ansible offers the highest expressiveness at the cost of the steepest entry barrier.

6. What Magento demands from the deploy tool

Magento places specific demands on the deployment process that go beyond a simple file transfer. The deploy tool must be able to correctly set symlinks for shared directories (pub/media, var/log) and shared files (app/etc/env.php). It must be able to run PHP commands on the target server, at minimum cache:flush, and where needed also setup:upgrade and setup:di:compile. It must guarantee the order of these steps and leave a defined state behind if something fails.

Deployer meets these requirements out of the box through its recipe system. Shell scripts can meet them too, but require explicit implementation and careful error handling. Ansible meets them via tasks and handlers, but is more complex than necessary for this purpose. For teams without an existing Ansible infrastructure, Deployer is the recommended choice for Magento deployments.

7. Typical failure patterns per tool

Every tool has typical failure patterns that arise from its specific weaknesses. With shell scripts, it is often a failed command that gets silently ignored because set -euo pipefail is missing, leaving the deploy in an inconsistent state. Or a shared symlink that got forgotten because it is set manually instead of being declaratively configured. Or a rollback that has to be performed by hand because no automatic path back was ever implemented.

With Deployer, problems often arise from task ordering: if Magento-specific tasks are hooked into the wrong point of the deploy sequence, setup:upgrade can end up running before the symlink switch or after the cache flush. With Ansible, the most common issues are incorrect idempotency assumptions, meaning a task that was not written idempotently produces errors on repeated runs, along with the absence of a genuine rollback concept, since Ansible is primarily geared toward restoring state rather than switching releases.

8. Decision matrix: which tool for which situation?

The decision is rarely absolute. Many teams start with shell scripts because it is the fastest path, and migrate to Deployer once rollback and multi-server support become important. Ansible gets introduced when the deployment problem turns into an infrastructure problem: when it is not just the application that needs deploying, but server configurations, cron jobs and service configurations that all need to stay in sync.

9. Migrating between the approaches

The most common migration path is from shell to Deployer. This migration carries low risk because both tools share the same infrastructure prerequisites: SSH access, a release directory structure, shared paths. The migration process: install Deployer, configure deploy.php with the existing parameters, test on staging first, then roll it out to production. The existing shell script stays in place as a fallback until Deployer has proven itself in production.

Migrating from Deployer to Ansible takes more effort, because Ansible works from a different mental model: instead of describing deployments, you describe the desired server state. This shift in paradigm requires reworking the entire deployment logic, not just a one-to-one transfer. Anyone planning this step should treat it as an infrastructure investment rather than a quick swap.

10. Summary

Comparing shell scripts, Deployer PHP and Ansible for Magento deployments in GitLab shows: there is no universally correct choice, but there are clear recommendations depending on context. Shell scripts suit simple single-server setups and work well as a fast starting point. Deployer PHP is the best choice for most Magento teams that need reliable release management and rollback capability. Ansible is worth adopting when deployment and infrastructure configuration have to be managed together.

The most common trap: starting with shell scripts and sticking with them too long, until the complexity becomes a burden. The right time to migrate to Deployer is when the shell script exceeds fifty lines, rollback becomes difficult, or a second server enters the picture. This step carries low risk when it is thoroughly tested on staging and the old script is kept around as a fallback.

11. FAQ: Shell scripts vs. Deployer vs. Ansible for Magento