Zendesk Global with contributions

Before proceeding, make sure you are comfortable with the requirements to perform this task. This is considerably more complex than other project setups. Consider working with someone who has experience doing these, such as a Fullstack Engineer, to ensure it is done properly.

Zendesk related projects that enable support contributions work via a system of GitLab CI/CD and git submodule.

Requirements

• As this is going to require adding a git submodule to the source project, you are going to need to be very comfortable with adding files and creating merge requests via CLI.
• This requires more complex CI/CD setup and coding, so make sure you have a firm grasp on GitLab’s CI/CD.
• This contains more complex git methodology, so make sure you are comfortable with “advanced” git techniques.

Setup the support contributions project

For the support contributions project, you will be creating it via the gitlab-com/support/zendesk-global group. Navigate there and click the blue New project button at the top-right of the page.

This will bring you to the new project page, showing various options to assist in the project’s creation. The option you want is Create blank project. After clicking that, you will need to fill out some information. It should be as follows:

• Project name: A name that specifies what the form is form
• Project URL: You are fine to allow gitlab.com to populate this for you
• Project deployment target (optional): Leave this as is and do not modify it
• Visibility Level: Private
• Project Configuration: Uncheck all boxes

After ensuring all that is solid, click the blue Create project button. This will result in an empty project being created.

Here you will need to add the initial content. This is going to vary depending on the nature of the project itself. Make sure to setup the .gitlab folder and its contents for the project!

Before leaving the project, you will also want to copy the Clone with SSH value for the target project. You can find this on the main page of the project by clicking the blue Code button and copying the value from there. Make sure to copy it somewhere you won’t lose it for now (such as a notepad), as you will need it in the next steps.

Once you have all that in place, you are good to move onto the next step.

Setup the source project

Next, you need to create the source project. To do this, first navigate to gitlab-support-readiness/zendesk-global and determine what area this falls into. As an example, if this is about tickets (such as forms, fields, settings, etc.), it might make sense to make the project in the Tickets subgroup. You will need to use your best discretion here to decide on that. Once you are in the group you are creating the project within, click the blue New project button at the top-right of the page.

This will bring you to the new project page, showing various options to assist in the project’s creation. The option you want is Create blank project. After clicking that, you will need to fill out some information. It should be as follows:

• Project name: A name that specifies what the form is form
• Project URL: You are fine to allow gitlab.com to populate this for you
• Project deployment target (optional): Leave this as is and do not modify it
• Visibility Level: Private
• Project Configuration: Uncheck all boxes

After ensuring all that is solid, click the blue Create project button. This will result in an empty project being created.

You will want to double check all the settings being used are accurate before proceeding.

After confirming the settings, you will want to create a merge request with the desired code, but this must be done via CLI. This is because we need to add the git submodule to the project.

Via CLI, you would want to ensure you are in the project’s root folder, then run the following command:

git submodule add CLONE_WITH_SSH_URL data/managed_content

You will replace CLONE_WITH_SSH_URL with the Clone with SSH value you copied from the support contributions project.

Add the rest of your code and then add it to the project. Keep in mind you need to:

• Make sure to setup the .gitlab folder and its contents for the project!
• Have CI/CD code for handling submodule updates (triggered via webhook)
• Have CI/CD code to report when something is out of date (triggers via commit to master)
• Have CI/CD code to perform a sync (triggered via pipeline schedule)
• Have the required variables for using git submodules via CI/CD, such as:

variables:
  GIT_SUBMODULE_STRATEGY: normal
  GIT_SUBMODULE_DEPTH: 1
  GIT_SUBMODULE_FORCE_HTTPS: 'true'

Make sure to:

• copy the project’s ID, as you are going to need it (the three vertical dots to the top-right of the page)
• copy the full path of the source project before proceeding, as you are going to need it (gitlab-support-readiness/zendesk-global/etc/etc).

Permissions Setup

Before we can proceed further, we need to setup some special permissions on the support contributions project to enable the source project’s use of the git submobule. Navigate to the support contributions project, hover over Settings, and click on CI/CD. Locate the Token Access section and click on Expand.

Ensure Limit access to this project is checked, and then click Add project to the right of Allow CI job tokens from the following projects to access this project. Here you will need to put the full path of the source project. After doing so, click the blue Add project button.

Webhook Setup

Next, we need to setup a webhook on the support contributions project to notify the source project when a commit is made to the master branch.

And to start that off, we need a pipeline trigger token from the source project. Navigate to the source project, hover over Settings on the project and click CI/CD. You will then navigate to the Pipeline trigger tokens section and click Expand. You will then click the Add new token button and enter a description that details what it is for (use the support contributions project’s URL). Once you have done so, click the blue Create pipeline trigger token button to generate the pipeline trigger token. Make sure to copy it somewhere like a notepad for use in whatever mechanism is calling the pipeline trigger. The info below the token contains various examples in how to use it.

Now navigate to the support contributions project, hover over Settings, and click Webhooks. Click Add new webhook and then use the following to get that filled out:

You then need to create a new webhook using the following information:

• URL: https://gitlab.com/api/v4/projects/PROJECT_ID/ref/master/trigger/pipeline?token=TOKEN
  • Replace PROJECT_ID with the ID of the source project
  • Replace TOKEN with the pipeline trigger token you generated earlier
• Click the bubble next to Mask portions of URL
  • Put the pipeline trigger token in the text field for Sensitive portion of URL
  • Put TOKEN in the text field for How it looks in the UI
  • Verify the URL preview value now looks like:
    • https://gitlab.com/api/v4/projects/PROJECT_ID/ref/master/trigger/pipeline?token=TOKEN{TOKEN}
• Check the box next to Push events
  • Select Wildcard pattern and enter master in the text field
• Check the box next to Enable SSL verification

Once all that is in place, click the blue Add webhook button.

CI/CD Setup

Once that merge request has been successfully merged into the default branch, you will then configure any needed CI/CD variables in the project’s settings. To do that, hover over Settings on the project and click CI/CD. You will then navigate to the Variables section and click Expand. For each variable you need (determined by your code and setup), you need to click the Add variable button to bring up a sub-menu. When doing these, ensure you uncheck the Protect variable box, uncheck the Mask variable box, and check the Expand variable reference box. Once you have entered your Key and Value, click the blue Add variable button.

The final step will be creating the pipeline schedule this will use.

To setup a pipeline schedule, hover over Build and click Pipeline schedules. Click the blue Create a new pipeline schedule button (for the first schedule) or the blue New schedule button (for subsequent ones). For the description, enter a description that states what it is doing (syncing to Zendesk, posting in Slack, etc.). For the Interval Pattern, enter a cron-style string that reflects when it will run (crontab.guru can help with that). For the Cron timezone, enter [UTC 0] UTC. For Select target branch or tag, use master (this is our default). If you have any variables dependent on this specific pipeline schedule, you can enter them here. Make sure the Activate checkbox is checked, and then click the blue Create pipeline schedule button.

Once that is done, so is the project setup!

NOTE You probably need to update some form of our handbook for this new project, so make sure that gets done!

View page source - Edit this page - please contribute.