Creating and Using Hooks

Use this guide to create stack hooks and automate builds on Cycle directly from your CI/CD workflow.

Create a Hook

To create a hook, follow these steps:

  1. Click the Stacks tab on the navigation menu to the left.
  2. Locate the stack the hook is associated with on the list, and click the name.
  3. Click the "Hooks" tab at the top of the page.
  4. Using the form on the right hand side, enter a name for the hook. The name is for identification purposes and has no impact on how it is used.
  5. Enter a default label. A default label is applied to a build if no label is present in the payload. More on this below.
  6. Click "Create Hook".

Using a Hook to Automatically Trigger A Stack Build

Once your hook is created, navigate to it by clicking its name on the list. You'll be taken to the hook's dashboard, where you can find the URL endpoints available, and the secret to send as part of the payload.

Labels And Versions

When hitting a hook, a label and a version can be specified. This information is passed on to the build that is generated, and will have implications in upcoming CI/CD features. Labels and versions are specified one of two ways. If you're using a generic hook, POST them along with the secret to the endpoint. If you're using a git-based integration, they can be specified via commit message using the following format:

  • [label: dev]
  • [version: v1]

where dev and v1 can be replaced with your specific values.

Example commit:

Fixed issue causing app to crash [label: dev] [version: 1.0.0-dev]

Triggering a Build Using Gitlab

Gitlab is a popular git repository management service. Cycle provides a hook endpoint that translates Gitlab webhook post data into a stack build.

  1. On the hook dashboard, select "Gitlab" for the URL type.
  2. Copy the URL using the blue copy icon on the right of the input.
  3. On Gitlab, follow this guide to create a push event webhook.
  4. In the "URL" field on Gitlab, paste in our copied URL.
  5. In the "Secret Token" field, paste in the hook secret that is found on the hook dashboard.

If configured correctly, your stack should create a new, labeled build every time you push.

Using a Generic Hook

Generic hooks are endpoints that can be triggered by sending a payload to the hook "default" endpoint. This is useful for creating custom CI/CD integrations or triggering a stack build via some other process.

The Payload

To trigger the hook, post the following to the "default" hook endpoint:

Example Post Data
{
"secret": "[YOUR SECRET]",
"label": "dev",
"version": "v1.0.0"
}

Customizing Integration

Requiring Labels

The git integration can be customized to require labels to exist in a commit message before the hook is triggered. To customize these options, go to the hook dashboard.

  1. On the form, select "Show Advanced".
  2. Check the "Require Label" checkbox.
  3. If you would like to require a version label before a hook can be triggered, select the "Require Version" checkbox.
  4. Click "Update Hook"

Deleting Hooks

Navigate to the hook dashboard and locate the Delete form in the right hand column below the update form. Just like with every resource on Cycle, you must enter the name of the hook in the box and hold down the delete button until the circle disappears to trigger the delete.

Need Help?

If you've got questions about the platform or need some help getting started, our team is more than happy to assist. Whether you're new to containers or just new to Cycle, reach out to us via livechat by clicking the blue circle in the bottom right corner. Join our Slack channel, and get help from the dev team or other members of the community, and check out our Roadmap to see what's planned for the future!