Using Shopify CLI for continuous integration

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.

• You've created an app with at least one registered function or app extension.
• You're using Shopify CLI 2.x.

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:

• App extensions
• Functions

1. 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.

2. From the app extension project root, open .env. The EXTENSION_UUID value will be passed as a parameter in your Shopify CLI automation.

1. 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.

2. From the function project root, open .env. The UUID value will be passed as a parameter in your Shopify CLI automation.

You can retrieve the API key and secret for your app from the Partner Dashboard.

1. From your Partner Dashboard, go to Apps.
2. Select the app that you want to push your function or app extension to.
3. 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.

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.

1. From your Partner Dashboard, navigate to Settings > CLI token, and then click Manage tokens.

2. 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.

3. From the Token expiration drop-down list, select an expiration for the token.

4. Click Generate token.

5. 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.

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.

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.

Additional examples

Explore working GitHub Actions workflows in our Shopify CLI sample app 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.