Deploy app components in a CD pipeline

If you have app configuration and extensions that you want to deploy to Shopify regularly, then you can integrate Shopify CLI into your CI/CD pipeline to programmatically deploy your app components using the deploy command.

Note that the deploy command deploys everything in your project at once. You can't deploy only some extensions. You also can't deploy your app configuration on its own.

Anchor to What you'll learnWhat you'll learn

In this tutorial, you'll learn how to set up your CI/CD pipeline to deploy your app programmatically. To do so, you'll gather the information necessary to run Shopify CLI commands, and then add a step to your CI/CD pipeline that installs Shopify CLI and deploys your app components.

Anchor to How it worksHow it works

Your app configuration and all extensions are versioned together as a single app version.

When you run the deploy command using Shopify CLI, an app version is created and released. You can revert to a previous app version at any time.

Releasing an app version replaces the current active version that's served to stores that have your app installed. It might take several minutes for app users to be upgraded to the new version.

Anchor to RequirementsRequirements

• You've scaffolded an app using the latest version of Shopify CLI.

Anchor to Step 1: Create a production app configuration fileStep 1: Create a production app configuration file

If you don't already have an app configuration file for the production copy of your app, then use the app config link command to create or link to an existing app.

Learn more about creating and linking app configurations.

Anchor to Step 2: Generate an App Automation TokenStep 2: Generate an App Automation Token

Create an App Automation Token through the Dev Dashboard. Open your app, go to Settings, and use the App Automation Token section to generate a token.

To learn more about creating and managing App Automation Tokens, refer to Manage App Automation Tokens.

Anchor to Step 3: Integrate Shopify CLI into your pipelineStep 3: Integrate Shopify CLI into your pipeline

After you retrieve your deployment variables and App Automation Token, you can integrate Shopify CLI into your continuous deployment pipeline using your CI/CD provider.

The CD pipeline step should install Shopify CLI.

To deploy to Shopify programmatically using your CD pipeline step, include the following:

• An environment variable that contains the App Automation Token that you generated in the Dev Dashboard.

  Info

  Where possible, you should protect the authentication token value by masking it or storing it as a secret.

• The name of your app configuration file that you created.

• A step that sets up Node.js and installs your project's Node dependencies. The package manager that you use should match your project's lockfile.

  • If you're using GitHub Actions, then you can use actions/setup-node.
  • If you're using CircleCI, then you can use circleci/node.

• Steps that install the other dependencies for your project.

• A step that runs the CLI deploy command with the --config and --allow-updates flags set.

Anchor to Link commits to app versionsLink commits to app versions

You can link a source control commit to an app version by adding the --source-control-url=<url> flag to the deploy command. The link that you provide appears in the details page for the app version in the Dev Dashboard. This information allows team members to easily view the corresponding source commit or revision for an app version.

To learn how to use this flag to provide a GitHub commit URL for an app version in your CI/CD workflow, refer to examples.

Anchor to Controlling extension and configuration deploymentControlling extension and configuration deployment

The --allow-updates and --allow-deletes flags on the app deploy and app release commands control the allowed changes to your app configuration and extensions in non-interactive terminal sessions.

• --allow-updates: Lets you deploy new app configuration and extensions, and update existing ones.
• --allow-deletes: Lets you delete app configuration and extensions.

Anchor to Additional project dependenciesAdditional project dependencies

The dependencies that are required to deploy your app extension depend on the technologies that you use to build the extension. Below are examples of common additional dependencies you'll need:

Anchor to ExamplesExamples

The sections below provide examples of common CI/CD pipeline tools: GitHub Actions and CircleCI.

Anchor to GitHub ActionsGitHub Actions

Below is an example of a step that you might add to your GitHub Actions workflow. It deploys app components to Shopify when code is pushed to the main branch.

The package manager that you use in your GitHub Action should match your project's lockfile.

name: Deploy app
on:
  push:
    branches:
      - main
jobs:
  deploy:
    name: Deploy
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v1
      - uses: actions/setup-node@v3
        with:
          node-version: 18
          cache: 'npm'
      - name: Install npm dependencies
        run: npm install
      - name: Install Shopify CLI
        run: npm install -g @shopify/cli@latest
      - name: Deploy
        env:
          # Token from the Dev Dashboard
          SHOPIFY_APP_AUTOMATION_TOKEN: ${{ secrets.SHOPIFY_APP_AUTOMATION_TOKEN }}
          COMMIT_URL: ${{ github.server_url }}/${{ github.repository }}/commit/${{ github.sha }}
        run: shopify app deploy --config production --allow-updates --source-control-url "$COMMIT_URL"

name: Deploy app
on:
  push:
    branches:
      - main
jobs:
  deploy:
    name: Deploy
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v1
      - uses: actions/setup-node@v3
        with:
          node-version: 18
          cache: 'yarn'
      - name: Install npm dependencies
        run: yarn install
      - name: Install Shopify CLI
        run: yarn global add @shopify/cli@latest
      - name: Deploy
        env:
          # Token from the Dev Dashboard
          SHOPIFY_APP_AUTOMATION_TOKEN: ${{ secrets.SHOPIFY_APP_AUTOMATION_TOKEN }}
          COMMIT_URL: ${{ github.server_url }}/${{ github.repository }}/commit/${{ github.sha }}
        run: shopify app deploy --config production --allow-updates --source-control-url "$COMMIT_URL"

name: Deploy app
on:
  push:
    branches:
      - main
jobs:
  deploy:
    name: Deploy
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v1
      - uses: actions/setup-node@v3
        with:
          node-version: 18
          cache: 'pnpm'
      - name: Install npm dependencies
        run: pnpm install
      - name: Install Shopify CLI
        run: pnpm install -g @shopify/cli@latest
      - name: Deploy
        env:
          # Token from the Dev Dashboard
          SHOPIFY_APP_AUTOMATION_TOKEN: ${{ secrets.SHOPIFY_APP_AUTOMATION_TOKEN }}
          COMMIT_URL: ${{ github.server_url }}/${{ github.repository }}/commit/${{ github.sha }}
        run: shopify app deploy --config production --allow-updates --source-control-url "$COMMIT_URL"

Anchor to CircleCICircleCI

The following config file defines a job that's triggered by a CircleCI workflow.

The package manager that you use in your job should match your project's lockfile.

version: 2.1
orbs:
  node: circleci/node@5.0.2
jobs:
  deploy:
    docker:
      - image: cimg/node:20.5.0
    environment:
      COMMIT_URL: << pipeline.project.git_url >>/commit/<<pipeline.git.revision>>
    steps:
      - checkout
      - node/install-packages:
          with-cache: true
      - run:
          name: Install Shopify CLI
          command: npm install -g @shopify/cli@latest
      - run:
          name: Deploy
          environment:
            # SHOPIFY_APP_AUTOMATION_TOKEN should be present as a secret
          command: |
            shopify app deploy --config production --allow-updates --source-control-url $COMMIT_URL
workflows:
  version: 2
  deploy:
    jobs:
      - deploy:
          filters:
            branches:
              only: main

version: 2.1
orbs:
  node: circleci/node@5.0.2
jobs:
  deploy:
    docker:
      - image: cimg/node:20.5.0
    environment:
      COMMIT_URL: << pipeline.project.git_url >>/commit/<<pipeline.git.revision>>
    steps:
      - checkout
      - node/install:
          install-yarn: true
      - node/install-packages:
          pkg-manager: yarn
          with-cache: true
      - run:
          name: Install Shopify CLI
          command: yarn global add @shopify/cli@latest
      - run:
          name: Deploy
          environment:
            # SHOPIFY_APP_AUTOMATION_TOKEN should be present as a secret
          command: |
            shopify app deploy --config production --allow-updates --source-control-url $COMMIT_URL
workflows:
  version: 2
  deploy:
    jobs:
      - deploy:
          filters:
            branches:
              only: main