DocumentationAPI Reference

Create a CI/CD pipeline for a Zendesk app

In this tutorial, you'll create a continuous integration and continuous deployment (CI/CD) pipeline for a Zendesk app. You'll use GitHub Actions and the Zendesk Command Line Interface (ZCLI) to create the pipeline.

Disclaimer: Zendesk provides this article for instructional purposes only. The examples are not meant for production environments. Zendesk doesn't provide support for this app or third-party technologies, such as GitHub.

What you'll need

To complete this tutorial, you'll need the following:

Create a Zendesk app

To start, use ZCLI to create a new app using one of the Zendesk app scaffolds. The scaffold will create the necessary file structure, manifest file, and entry points for your app. There are two options:

  • Basic app scaffold (option 1)

    zcli apps:new

    or

    zcli apps:new --scaffold=basic

  • Zendesk React app scaffold (option 2)

    zcli apps:new --scaffold=react

    Tip: If you're new to the Zendesk React app scaffold, refer to Tips for using the React app scaffold.

Both of the above options will prompt you for the following:

  • The installation path
  • Your name
  • Your email
  • Your website (optional)
  • Name of your app

Tip: You can also pass the above bullet points as optional flags when creating the app:

zcli apps:new --appName="Foo App" --authorEmail=[email protected] --authorName="Foo Bar" --path=zcliCi

For the React app scaffold, add --scaffold=react to the above command.

Setting up CI with GitHub Actions

GitHub Actions allow you to automate and customize workflows in your GitHub repositories. You can learn more in the GitHub Actions documentation.

Creating a new repository

Next, create a repository for your Zendesk app on GitHub. A repo is required to use GitHub actions.

  1. In your browser, go to GitHub and create a new repository.

    Note: Keep the repo empty. Don't add a README or a .gitignore file to the repo. Your app files include a README. You can add a .gitignore file later.

  2. In your shell, navigate to your project's root directory. Example:

    cd projects/cicd_test_app

  3. Run the following git commands to push your changes to the GitHub repo:

    git init git remote add origin [email protected]:{path_to_your_repo)git branch -M maingit add -Agit push -u origin main

Setting up GitHub Actions

  1. In your project's root directory, create a .github/workflows folder:

    mkdir .github | mkdir .github/workflows

  2. In .github/workflows, create an actions.yml file. You can use the actions.yml file to define inputs, outputs, and runs configurations for your GitHub Actions.

    touch actions.yml

You now have a structure you can use to create a CI/CD pipeline with GitHub Actions. We've included three example commands below. You can pick and choose the commands that work best for your workflows.

It's possible to run multiple commands from one YAML file. However, using a single YAML file can introduce minor issues. To avoid these issues, we recommend you create a separate YAML file for each command.

Example GitHub Actions files for ZCLI

GitHub Actions has a deep set of tools to build automated workflows. For more information, refer to the GitHub Actions documentation.

The example commands in this article may not fit with the best practices of your production environment. These examples should be used as proof of concepts, not production-ready workflows.

Each of the example commands builds off the following template.

name: ZCLI template
# Triggers the workflow...on:  # ...when you push...  push:    # ...to branch "main"     branches: [main]  # ...when you manually click "Run Workflow" on GitHub from the Actions page    workflow_dispatch:
# If the worflow is triggered by one of the above options...
# ...jobs will kick off to...jobs:  # ...create a build using...  build:    # ...the latest version of Ubuntu...    runs-on: ubuntu-latest    # ...using Node version 16.x...    strategy:      matrix:        node-version: [16.x]
# With the environment setup, we can begin taking action...        # ...with these steps...    steps:      # Until the next comment, these are default actions for the Node.js template from GitHub      - uses: actions/checkout@v3      - name: Use Node.js ${{ matrix.node-version }}        uses: actions/setup-node@v3        with:          node-version: ${{ matrix.node-version }}          # Uncomment the next line only when using React          # cache: 'npm'      # ...install the Zendesk CLI      - name: Install zcli        run: npm i @zendesk/zcli -g

zcli apps:bump

This command will change the semantic version (semvar) of your Zendesk app, located in the manifest.json. It increments major (1.x.x), minor (x.1.x), and/or patch (x.x.1) by one with optional flags that can be attached to the command. If you run the command without a flag, it will bump the patch version.

  • bash zcli apps:bump or bash zcli apps:bump -p - increments patch version
  • bash zcli apps:bump -m - increments minor version
  • bash zcli apps:bump -M - increments major version

Creating the workflow for "bump"

To use the bump command in a workflow, we needed to use a triggering event for each of the different versions. For demonstration purposes, we decided to use commit messages to trigger the different version increments. This method should not be used in a production environment. Any comment that contains one of these words could potentially throw off your versioning. This example is just a starting point and proof of concept.

Edit the actions.yml file located in .github/workflows by adding lines 3-23 in the above template with the following:

name: ZCLI bump
# Replace this line with lines 3-23 from the template    #...and these authentication details, which are pulled from your Actions secrets        env:      ZENDESK_SUBDOMAIN: ${{  secrets.SUBDOMAIN  }}      ZENDESK_EMAIL: ${{  secrets.EMAIL  }}      ZENDESK_API_TOKEN: ${{  secrets.API_TOKEN  }}
    # With the environment setup, we can begin taking action with these steps...    steps:      # Default Node.js workflow...      - uses: actions/checkout@v3      - name: Use Node.js ${{ matrix.node-version }}        uses: actions/setup-node@v3        with:          node-version: ${{ matrix.node-version }}          # Uncomment the next line only when using React          # cache: 'npm'      # ...install the Zendesk CLI      - name: Install zcli        run: npm i @zendesk/zcli -g      # These next three actions will run if the commit message contains the word in each 'if' condition. If your commit message contains all three words, each action will run. Basically, don't use this workflow in a production environment!      - name: Bump patch version         if: contains(github.event.head_commit.message, 'patch')        run: zcli apps:bump -p      - name: Bump minor version        if: contains(github.event.head_commit.message, 'minor')        run: zcli apps:bump -m      - name: Bump major version         if: contains(github.event.head_commit.message, 'major')        run: zcli apps:bump -M      # Finally, we need to push the changes to our repository. Since GitHub Actions run in a separate environment, the above changes won't update your repo without this.      - name: Update repo         run: |             git config --global user.email "[your GH email]"             git config --global user.name "[your name]"                          git add -A             git commit -m "Commit message             git push

zcli apps:update

This command will validate, package, and update your installed Zendesk app. You will need to create encrypted secrets for this repo, which will contain your Zendesk subdomain, email address, and an API token.

Creating GitHub Actions secrets

Note: You will need to complete these steps three times for the three secrets listed in the fifth step.

  1. On GitHub, navigate to the main page of the repo.
  2. On the repo page, click Settings.
  3. In the left sidebar, click Secrets > Actions.
  4. Click New repository secret.
  5. Create each of the three following secrets (in all CAPS):
    • SUBDOMAIN
    • EMAIL
    • API_TOKEN
  6. Enter a value for each of the three secrets:
    • For SUBDOMAIN, use only the portion of your subdomain before ".zendesk.com." For example, in "example.zendesk.com," you will enter only "example."
    • For EMAIL, enter your email address. You do NOT need to append "/token" to your email address as you normally do when using an API token in Zendesk.
    • For API_TOKEN, copy and paste an available API token from your account.
  7. Click Add secret.

Creating the workflow for "update"

For update, we need to add a JSON config file that contains the installation id of the app in your Zendesk instance.

  1. From a browser, go to https://{subdomain}.zendesk.com/api/v2/apps/installations.

  2. Find your app by name and then copy the id value above it.

  3. Open a terminal window and create the JSON file from your project root:

    touch zcli.apps.config.json

  4. Open the file in your editor, add the id, and save the file:

    { "app_id": APP_ID }

Edit the actions.yml file located in .github/workflows by adding lines 3-23 in the above template with the following:

name: ZCLI update
# Copy/paste lines 3-23 from the template from above...    #...and these authentication details, which are pulled from your Actions secrets        env:      ZENDESK_SUBDOMAIN: ${{  secrets.SUBDOMAIN  }}      ZENDESK_EMAIL: ${{  secrets.EMAIL  }}      ZENDESK_API_TOKEN: ${{  secrets.API_TOKEN  }}
# With the environment setup, we can begin these steps...    steps:      # Until the next comment, these are default actions for the Node.js template from GitHub      - uses: actions/checkout@v3      - name: Use Node.js ${{ matrix.node-version }}        uses: actions/setup-node@v3        with:          node-version: ${{ matrix.node-version }}          # Uncomment the next line only when using React          # cache: 'npm'      # ...install the Zendesk CLI      - name: Install zcli        run: npm i @zendesk/zcli -g      - name: Deploy the app        run: zcli apps:update

Note: If you built your app with React, you will need to run the build command you've set up in your package.json file. You will also need to install dependencies. To take these steps, replace the last two lines in the "update" workflow from above with this:

# For React app scaffold      - name: Install app dependencies        run: npm install      - name: Create dist directory        run: npm run build      - name: Deploy the app        run: zcli apps:update dist

zcli apps:validate

This command runs a suite of tests to ensure that your app is ready to be packaged and uploaded to a Zendesk instance. If you run zcli apps:update, you do not need to validate beforehand, as the validation is already part of the update process.

You will need to use the same setup for Github Actions secrets that we created for "update." Refer to Creating GitHub Actions secrets.

Creating the workflow for "validate"

Edit the actions.yml file located in .github/workflows by adding lines 3-23 in the above template with the following:

name: ZCLI validate
# Copy/paste lines 3-23 from the template from above...    #...and these authentication details, which are pulled from your Actions secrets        env:      ZENDESK_SUBDOMAIN: ${{  secrets.SUBDOMAIN  }}      ZENDESK_EMAIL: ${{  secrets.EMAIL  }}      ZENDESK_API_TOKEN: ${{  secrets.API_TOKEN  }}
# With the environment setup, we can begin taking these steps...    steps:      # Until the next comment, these are default actions for the Node.js template from GitHub      - uses: actions/checkout@v3      - name: Use Node.js ${{ matrix.node-version }}        uses: actions/setup-node@v3        with:          node-version: ${{ matrix.node-version }}          # Uncomment the next line only when using React          # cache: 'npm'      # ...install the Zendesk CLI      - name: Install zcli        run: npm i @zendesk/zcli -g      - name: Validate the app        run: zcli apps:validate .

Note: If you built your app with React, you will need to run the build command you've set up in your package.json file. You will also need to install dependencies. To take these steps, replace the last two lines in the "validate" workflow from above with this:

# For React app scaffold      - name: Install app dependencies        run: npm install      - name: Create dist directory        run: npm run build      - name: Validate the app        run: zcli apps:validate dist

Tips for using the React app scaffold

Key differences when using React:

  • We need to run npm install to install the necessary dependencies (webpack etc.) to build our app.
  • We need to run npm run build to kick off our app files being compiled to the dist folder.
  • When using the "validate" or "update" commands, we need to specify the path as our manifest file does not live in the root directory. In this case, we point to the dist folder that we created in our workflows.