Using Shopify CLI for continuous integration
If you have an app extension or script that you want to push to Shopify regularly, then you can integrate Shopify CLI into your CI/CD pipeline to programmatically push your app components using shopify extension push
or shopify script push
.
You can push the following app components using Shopify CLI in a CI/CD pipeline:
What you'll learn
Anchor link to section titled "What you'll learn"In this tutorial, you'll learn how to set up your CI/CD pipeline to push your functions and app extensions programmatically. To do so, you'll gather the information necessary to run the CLI commands programmatically, and then add a step to your CI/CD pipeline that installs the Shopify CLI and pushes your app extension or function to Shopify.
Requirements
Anchor link to section titled "Requirements"- You've created an app with at least one registered function or app extension.
- You're using Shopify CLI 2.x.
Step 1: Retrieve your extension ID or UUID
Anchor link to section titled "Step 1: Retrieve your extension ID or UUID"To push your app extension or function to Shopify, you need an ID that's unique to your app extension or function. This ID is stored in an .env
file in the root directory of your app extension or Shopify Functions project. You can generate this file and ID by registering your app extension or function, or by connecting your local project directory to an existing app extension or function in your Partner organization.
To generate an .env
file and retrieve your ID, follow one of the sections below, depending on your project type:
Retrieve an app extension ID
Anchor link to section titled "Retrieve an app extension ID"Run one of the following commands to generate an
.env
file for your app extension project:App extension commands that can create an `.env` file Command Usage shopify extension register
Creates your app extension and associates it with an app in your Partner organization. This step should be done only once for each app extension.
This operation can't be undone.shopify extension connect
Creates your app extension and associates it with an app in your Partner organization. This step should be done only once for each app extension. This operation can't be undone. From the app extension project root, open
.env
. TheEXTENSION_UUID
value will be passed as a parameter in your Shopify CLI automation.
Retrieve a function UUID
Anchor link to section titled "Retrieve a function UUID"Run
shopify script connect
to generate an.env
file for your Shopify Functions project.This command associates your function with an app in your Partner organization. This step should be done only once for each function.
From the function project root, open
.env
. TheUUID
value will be passed as a parameter in your Shopify CLI automation.
Step 2: Retrieve your API key and secret
Anchor link to section titled "Step 2: Retrieve your API key and secret"You can retrieve the API key and secret for your app from the Partner Dashboard.
- From your Partner Dashboard, go to Apps.
- Select the app that you want to push your function or app extension to.
- From the API keys section, copy your API key and API secret key.
These values will be passed as parameters in your Shopify CLI automation.
Step 3: Generate a CLI authentication token
Anchor link to section titled "Step 3: 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.
Generate a CLI authentication token in the Partner Dashboard
Anchor link to section titled "Generate a CLI authentication token in the Partner Dashboard"- From your Partner Dashboard, navigate to Settings > CLI token, and then click Manage tokens.
Select the appropriate access for your authentication token:
- UI extensions: For extension projects such as product subscription app extensions and checkout UI extensions
- Functions: For Shopify Functions projects such as payment method functions
After the token is created, these permissions can't be changed.
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.
Step 4: Integrate Shopify CLI into your pipeline
Anchor link to section titled "Step 4: Integrate Shopify CLI into your pipeline"After you retrieve your extension ID and CLI authentication token, you can integrate Shopify CLI into your continuous integration pipeline using your CI/CD provider.
The CI pipeline step should install Shopify CLI and all of its dependencies.
To push to Shopify programmatically using your CI pipeline step, include the following:
- An environment variable that contains the authentication token that you generated in the Partner Dashboard.
- The
push
command with the following parameters:--extension-id
(extensions only): The ID of your app extension that you retrieved from your.env
file.--uuid
(functions only): The ID of your function that you retrieved from your.env
file.--api-key
: The API key for your app that you retrieved from the Partner Dashboard.--api-secret
: The API secret key for your app that you retrieved from the Partner Dashboard.--force
(functions only): Replaces the current function with the newest version. This parameter is required.
Where possible, you should protect the authentication token, extension ID, and API key and secret parameter values by masking them or storing them as secrets.
The sections below provide examples of common CI/CD pipeline tools: GitHub Actions and CircleCI.
GitHub Actions
Anchor link to section titled "GitHub Actions"Shopify provides a CLI GitHub Action that you can reference in your GitHub Actions workflow. This GitHub Action installs Shopify CLI and its dependencies for you.
Below is an example of a step that you might add to your GitHub Actions workflow. It pushes script code to Shopify when code is pushed to the main
branch. The extension ID and API key are stored as secrets in the GitHub repository.
The following config file defines a job that's triggered by a CircleCI workflow. The extension ID and API key are stored as masked environment variables in the CircleCI project.