servd

Documentation

Documentation > Project Settings >

Webhooks

You can add webhooks to both GitHub, GitLab and Bitbucket in order to automatically trigger bundle builds and deployments whenever you push a new commit to a nominated branch.

Builds triggered by a webhook will use the same base software and directory map as your most recent, manual bundle build.

1. Creating the Webhook in Servd #

  2. In the webhooks section, enter the branch that you would like to track with your automated builds.

  3. Select whether you want the webhook to fire when the updated branch:

    • Matches the branch registered with the webhook exactly.
    • Starts with the branch registered with the webhook.
    • Ends with the branch registered with the webhook.
    • Or is found somewhere in the branch registered with the webhook.

  4. Optionally select an environment that you'd like to automatically deploy new bundles to.

  5. Make a note of the webhook URL and secret. You'll need them in a moment.

  6. Depending on who you store your repo with, carry on to the GitHub, GitLab or Bitbucket instructions below. 👇

2. Setting up the Webook with your Git Respository #

Next, you need to configure your git repository provider to send updates to Servd. Here are some instructions for doing that if you use GitHub, GitLab, Bitbucket or an external CI provider.

GitHub #

  1. Open a browser tab and navigate to your Git repo on GitHub. Find the 'Settings' section and select 'Webhooks'.

  2. Click 'Add Webhook'

  3. Enter the webhook URL and secret from the Servd dashboard into the appropriate fields.

    1. Set the 'Content Type' to 'application/json'.
    2. Select 'Just the push event'
    3. Ensure 'Active' is checked.

  4. Click 'Add Webhook' and you're done! The next commit added to your nominated branch will trigger a bundle to be built in Servd.

Debugging Github Webhooks

If your webhook isn't working as expected, the best place to debug is on the 'Recent Deliveries' tab within the Github Webhook Settings.

This page will show you all of the recent attempts that GitHub has made to trigger the webhook, along with the response from Servd. Checking this response for errors will usually reveal the problem.

GitLab
#

  1. Open a browser tab and navigate to your Git repo on GitLab. Find the 'Settings' section and select 'Integrations'.

  2. Enter the webhook URL and secret obtained from the Servd dashboard.

    Check only 'Push Events' (everything else will be ignored anyway)

  3. Click 'Add Webhook' and you're done! The next commit added to your nominated branch will trigger a bundle to be built in Servd.

Bitbucket #

  1. Open a browser tab and navigate to your Git repo on Bitbucket. Find the 'Repository Settings' section and select 'Webhooks'. Click 'Add Webhook'.

  2. Give the webhook a name and paste the webhook URL obtained from the Servd dashboard.

    Check that 'Triggers' is set to 'Repository Push'

  3. Click 'Save' and you're done! The next commit added to your nominated branch will trigger a bundle to be built in Servd.

Via An External CI Provider #

Servd supports building a bundle from an archive of files instead of from a git commit. This can be handy if you want to do some custom preprocessing of files before they're passed over to us.

The steps for your CI platform will look a little like this...

  1. Clone your repo.
  2. Perform any relevant preprocessing e.g. compiling CSS and JS assets.
  3. Make sure all compiled assets are in their final locations inside your repo's directory structure (probably somewhere inside your web folder).
  4. Use the Servd Custom Webhook Script to archive and upload your files.

Servd Custom Webhook Script?

This script can automate the archive and upload of your a craft base directory and trigger a bundle build based on the contents of this archive.

You can run it using a single command in your CI script which looks like this:

curl -L https://app.servd.host/servd-webhook-script | sh -s [project-slug] [webhook-secret] [commit-sha] [path-to-craft-base-dir] [comment] [branch]

The arguments are as follows:

  • [project-slug] - Your project's slug from the Servd dashboard
  • [webhook-secret] - Your project's webhook secret from the Servd dashboard
  • [commit-sha] - The SHA of the commit you're currently working with. This is usually supplied as an $ENVIRONMENT_VARIABLE by your CI platform
  • [path-to-craft-base-dir] - A relative or absolute path to your craft base directory (containing config, web, templates etc)
  • [comment] - A comment to attach to the bundle. It's usually a good idea to just use the first line of the Git commit comment
  • [branch] - The branch that the commit belongs to. This can be used to trigger webhooks from your project build settings.

A real world example from Gitlab CI which we use to deploy the servd.host website:

curl -L https://app.servd.host/servd-webhook-script | sh -s $SERVD_PROJECT_NAME $SERVD_SECRET $CI_COMMIT_SHA ./src "${CI_COMMIT_TITLE}" $CI_COMMIT_BRANCH

GitLab supplies the $CI_* variables and we have defined the others as 'secrets' in the GitLab dashboard. Your CI provider of choice should allow you to do something similar.