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.
The shopify app config push
Shopify CLI command is no longer supported. If you're using this command in your workflow, follow these steps to update app configuration with the deploy
command.
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
When you run the deploy
command, the app version includes the latest drafts of all dashboard-managed extensions.
Any CLI-managed extensions that aren't present in the environment you're deploying from are removed.
Your app configuration and all extensions, including extensions created in the Partner Dashboard, 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.
If you want to create a version without releasing it to users, then run the deploy
command with a --no-release
flag.
You can release the unreleased app version using Shopify CLI's release
command, or through the Partner Dashboard.
Anchor to RequirementsRequirements
Anchor to Step 1: Generate variables for deploymentStep 1: Generate variables for deployment
To target the app that you want to deploy to, you need to gather your app's client ID.
-
Navigate to your app directory.
-
Run the following command:
Terminal
shopify app deploy
An env
file is generated at the root of your project. It contains the client ID (API key) for your app and the ID of each of the extensions in your app.
Anchor to Step 2: Generate a CLI authentication tokenStep 2: Generate a CLI authentication token
You can create a new CLI authentication token through the Partner Dashboard.
Tokens are managed at the Partner organization level. You can have only two CLI authentication tokens for your Partner organization. If you want to create more than two authentication tokens, then you need to delete an existing authentication token.
Anchor to Generate a CLI authentication token in the Partner DashboardGenerate a CLI authentication token in the Partner Dashboard
-
From your Partner Dashboard, navigate to Settings > CLI token, and then click Manage tokens.
-
From the Token expiration drop-down list, select an expiration for the token.
-
Click Generate token.
-
In the Tokens section, click the Copy button to copy the access token to your clipboard.
This token value will be passed as a parameter in your Shopify CLI automation.
For security reasons, the token is only visible immediately after it's created. If you lose your token, then you need to delete your existing token and then generate a new token.
Anchor to Step 3: Integrate Shopify CLI into your pipelineStep 3: Integrate Shopify CLI into your pipeline
After you retrieve your deployment variables and CLI authentication 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 authentication token that you generated in the Partner Dashboard.
-
The client ID for your app (
SHOPIFY_API_KEY
), which you generated in step 1. -
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--force
flag set.Where possible, you should protect the authentication token and client ID values by masking them or storing them as secrets.
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 Partner 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 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:
App extension type | Additional dependencies |
---|---|
Extensions that use Shopify Functions, including product, order, and shipping discount extensions | Your function language |
Anchor to ExamplesExamples
The sections below provide examples of common CI/CD pipeline tools: GitHub Actions and CircleCI.
Anchor to GitHub ActionsGit Hub 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.
.github/workflows/deploy-extensions.yml
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 Partner Dashboard
SHOPIFY_CLI_PARTNERS_TOKEN: ${{ secrets.SHOPIFY_CLI_PARTNERS_TOKEN }}
COMMIT_URL: ${{ github.server_url }}/${{ github.repository }}/commit/${{ github.sha }}
# .env content after a deploy
SHOPIFY_API_KEY: xxxx
run: shopify app deploy -f --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 Partner Dashboard
SHOPIFY_CLI_PARTNERS_TOKEN: ${{ secrets.SHOPIFY_CLI_PARTNERS_TOKEN }}
COMMIT_URL: ${{ github.server_url }}/${{ github.repository }}/commit/${{ github.sha }}
# .env content after a deploy
SHOPIFY_API_KEY: xxxx
run: shopify app deploy -f --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 Partner Dashboard
SHOPIFY_CLI_PARTNERS_TOKEN: ${{ secrets.SHOPIFY_CLI_PARTNERS_TOKEN }}
COMMIT_URL: ${{ github.server_url }}/${{ github.repository }}/commit/${{ github.sha }}
# .env content after a deploy
SHOPIFY_API_KEY: xxxx
run: shopify app deploy -f --source-control-url "$COMMIT_URL"
Anchor to CircleCICircle CI
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.
.circleci/config.yml
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_CLI_PARTNERS_TOKEN should be present as a secret
# .env content after a deploy
SHOPIFY_API_KEY: xxxx
command: |
shopify app deploy -f --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_CLI_PARTNERS_TOKEN should be present as a secret
# .env content after a deploy
SHOPIFY_API_KEY: xxxx
command: |
shopify app deploy -f --source-control-url $COMMIT_URL
workflows:
version: 2
deploy:
jobs:
- deploy:
filters:
branches:
only: main