Ziti Webhook Action

This GitHub workflow action uses Ziti NodeJS SDK to post an event's payload in JSON format over a Ziti connection.

MacOS Compatibility

If you have a MacOS job you may wish to use @v1 ref which works with the macos-latest hosted runner.

Usage

name: ziti-webhook-action
on: [ push ]

jobs:
  ziti-action:
    runs-on: ubuntu-latest
    name: Ziti Webhook Action
    steps:
    - uses: openziti/ziti-webhook-action@v2
      with:
        # Identity JSON containing key to access a Ziti network
        ziti-id: ${{ secrets.ZITI_WEBHOOK_ACTION_ID }}

        # URL to post event payload.  Note that the Ziti service
        # name must match the hostname of the URL (e.g.
        # "someapp.ziti")
        webhook-url: https://someapp.ziti/plugins/github/webhook

        # Used to create a hash signature of the payload
        # to be set in the X-Hub-Signature HTTP header
        webhook-secret: ${{ secrets.ZITI_WEBHOOK_SECRET }}

Ziti Identity

The ziti-id input is the JSON formatted string of an identity enrolled in a Ziti network.

The identity JSON is created by running the ziti edge enroll ./ziti-id.jwt command. The one-time token file e.g. "ziti-id.jwt" is typically downloaded from the web console or output when the identity is created.

# example of saving the token file when the identity is created
ziti edge create identity device my-ziti-identity --jwt-output-file ./ziti-id.jwt

The ziti executable can be obtained here.

Alternatively, you may run the ziti executable with Docker.

docker run --rm --volume ${PWD}:/mnt openziti/quickstart /openziti/ziti-bin/ziti edge enroll /mnt/ziti-id.jwt

WebHook Secret

This is a random secret string that is used to provide a data integrity hash the receiver may validate. Validation logic that works with GitHub webhooks also works with ziti-webhook-action. From that reference:

ruby -rsecurerandom -e 'puts SecureRandom.hex(20)'

Or, generate the random string with Python.

python -c "import os, binascii; print(binascii.hexlify(os.urandom(20)).decode('utf-8'))"

Extra Data Input

There are two ways to pass arbitrary data to be included in the webhook.

1. Call the Action in a separate workflow with a raw-field. This causes the GitHub context payload to have a top-level dict named inputs with a key for each workflow input. This is useful if this Action is always called from another workflow.

on:
  workflow_dispatch:  # triggered by a step in the main workflow
    inputs:
      my_release_version:
        description: 'Semantic Version from Builder Bot'
        required: true

This example results in a top-level dict in the webhook payload.

# One way to pass a raw field is to use the GitHub CLI which is pre-installed in all hosted runner VMs
gh workflow --repo myorg/myrepo run --ref $(git rev-parse --abbrev-ref HEAD) --raw-field my_release_version=1.2.3 send-ziti-webhook.yml

{
  "inputs": {"my_release_version": "1.2.3"}
}

2. A multi-line string with key=value pair / line may be passed to the data input field of the Action. This is useful if the Action is called in-line as part of a workflow that contains other steps.

        with:
          ziti-id: ${{ secrets.ZITI_WEBHOOK_IDENTITY }}
          webhook-url: https://someapp.ziti/plugins/github/webhook
          webhook-secret: ${{ secrets.ZITI_WEBHOOK_SECRET }}
          data: |
            my_release_version=1.2.3

Results in:

{
  "data": {"my_release_version": "1.2.3"}
}