Deployment Overview

In Magento version 2.2, we introduce a new way to deploy to production with minimal downtime. We refer to this as pipeline deployment because the deployment process occurs on different systems.

We also provide the ability to maintain consistent configurations for all pipeline deployment systems. It’s a simple but powerful model that enables you to separate ordinary configuration settings from either system-specific settings (like host and port) or sensitive settings (such as names and passwords).

Reduced downtime deployment

Because you deploy static assets and compile code on a machine separate from your production system, you minimize downtime. Downtime on your production system is limited to the amount of time required to transfer static files and compiled code to the server.

Deployment systems

We use the following terms to describe the systems involved with deployment.

Development system
Machine on which developers work to customize code; and install extensions, themes, and language packages from Magento Marketplace. In addition, you make all configuration changes on your development system. You can have many development systems.
Build system
One system on which you deploy static assets and compile code for your production system. Because you build these assets on a system not in production, your production system’s downtime is minimized.

Your build system does not have to have Magento installed on it. It needs only the Magento code but no database connection is required. Also, your build system doesn’t need to be a physically separate server.

Staging system
Optional. You can optionally set up a staging system to use for final testing of all integrated code, including User Acceptance Testing (UAT). Set up a staging system the same way you set up a production system. Except for the fact that staging is not your live store and doesn’t process orders from customers, it’s identical to production.
Production system
Your live store. You should make minimal configuration changes here and no changes to:
  • websites
  • stores
  • store views
  • products
  • product view settings
  • catalog
  • categories
  • category view settings.

You should make all those types of changes in your development system.

Other deployment methods

You can optionally use other deployment methods, including:

Manage the configuration

Modeling after factor 3 in the 12-factor app design, Magento now stores the configuration for each system in the system itself. (Development configuration settings are stored on the development system, production settings are stored on the production system.)

We also provide a way to synchronize the configuration of your systems:

  • Shared configuration, which is all settings that are neither system-specific nor sensitive.

    Shared settings are settings you want to be consistent on development and production systems. Set the shared configuration in the Magento Admin in your development (or Magento Commerce Cloud integration) system.

    The shared configuration file, app/etc/config.php, should be included in source control so it can be shared between development, build, and production systems.

  • System-specific configuration, which is all settings that vary by system; for example, search engine hostnames and ports.

  • Sensitive configuration, which is all settings that should not be in source control because they expose personally-identifiable information (PII) or settings such as API keys or passwords.

    The system-specific configuration file, app/etc/env.php, should not be included in source control or otherwise shared between systems. Instead, use the magento config:set and magento:sensitive:set commands to provide values for those settings in your production system.

These new methods to manage your configuration are optional. You don’t have to use them, although we strongly recommend you do.

Most of the time, the configuration options you set in the shared, system-specific, or sensitive configuration cannot be edited in the Magento Admin. This helps keep your settings consistent across all systems. (You can optionally use the magento config:set command without the --lock option to configure settings that are editable in the Admin.)

Each Magento configuration option has a unique configuration path. To set a value for a configuration option, you can use either a CLI command or an environment variable to set the value for that configuration path on a specific system.

For a complete list of configuration paths, see the following references:


To use pipeline deployment, we assume you are:

  • An experienced system integrator with excellent knowledge of Magento configuration options.
  • Managing a large Magento site (thousands of stock-keeping units (SKUs)) and want to keep production site downtime to a minimum.
  • Somewhat knowledgeable about PHP programming.
  • Experienced with source control methods.

    To use pipeline deployment, we assume your Magento code is in a source control repository. In this guide, we assume you’re using Git but the choice of repositories is up to you.

Related topics

Deployment technical overview (implementation details)