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:
-
ZCLI. To install or upgrade ZCLI, refer to Installing and updating ZCLI. ZCLI replaces the Zendesk Apps Tools (ZAT), which are in maintenance mode.
-
Familiarity with Zendesk Apps. Before starting, we recommend you complete the Building your first Support app tutorial.
-
A GitHub account. To create an account, refer to Signing up for a new GitHub account.
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.
-
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.
-
In your shell, navigate to your project's root directory. Example:
cd projects/cicd_test_app
-
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 main
git add -A
git push -u origin main
Setting up GitHub Actions
-
In your project's root directory, create a .github/workflows folder:
mkdir .github | mkdir .github/workflows
-
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 20.x...
strategy:
matrix:
node-version: [20.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
orbash zcli apps:bump -p
- increments patch versionbash zcli apps:bump -m
- increments minor versionbash 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.
- On GitHub, navigate to the main page of the repo.
- On the repo page, click Settings.
- In the left sidebar, click Secrets > Actions.
- Click New repository secret.
- Create each of the three following secrets (in all CAPS):
- SUBDOMAIN
- API_TOKEN
- 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.
- 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.
-
From a browser, go to https://
{subdomain}.zendesk.com/api/v2/apps/installations . -
Find your app by name and then copy the
id
value above it. -
Open a terminal window and create the JSON file from your project root:
touch zcli.apps.config.json
-
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.