Skip to content
Zekt Docs

Quickstart: your first event

In this quickstart, a provider workflow sends an event with a small payload, and a consumer workflow in another repository runs when it arrives.

You need:

  • two Zekt accounts: one with the Provider persona, and one with Consumer (or Both) (sign up);
  • two GitHub repositories where you have admin permission: one for the provider account to send from, one for the consumer account to receive in. Each repository can belong to only one Zekt account.

1. Set up the provider

Section titled “1. Set up the provider”

Sign in to Zekt as the provider account.

  1. Enable the repository. Go to Provider → Repos and turn on the toggle for your provider repository. Install the Zekt GitHub App on it if asked: choose Only select repositories. Details.

  2. Add a workflow that sends an event. Commit this to .github/workflows/hello-zekt.yml:

    name: Hello Zekt
    on: workflow_dispatch
    permissions:
      id-token: write
      contents: read
    jobs:
      send:
        runs-on: ubuntu-latest
        steps:
          - uses: zekt-dev-org/zekt-action@v3
            with:
              event-type: hello-zekt
              payload: |
                {"greeting":"hello from the provider"}

  3. Whitelist the workflow. Go to Provider → Workflows, select the repository, and turn on the toggle next to the workflow, listed by its file name hello-zekt.yml. Details.

  4. Create the service. Go to Provider → Service Descriptions, stay on the Provider Services sub-tab, and choose Create New. Choose the repository and the hello-zekt.yml workflow, and set Dispatch Event Type to hello-zekt. Turn on Publish to Directory and choose Public, so the consumer account can find it. Choose Save Service Description.

2. Set up the consumer

Section titled “2. Set up the consumer”

Sign in to Zekt as the consumer account.

  1. Enable the repository. Go to Consumer → Repos and turn on the toggle for your consumer repository. Keep Track Workflow Completion ticked, choose Continue to GitHub, and finish with Enable Consumer Repository. Details.

  2. Add a workflow that receives the event. Commit this to the default branch as .github/workflows/on-hello-zekt.yml:

    name: On hello-zekt
    on:
      repository_dispatch:
        types: [hello-zekt]
    run-name: ${{ github.event.client_payload.zekt.dispatch_id }}
    jobs:
      receive:
        runs-on: ubuntu-latest
        steps:
          - env:
              GREETING: ${{ github.event.client_payload.zekt.payload.greeting }}
              CONCLUSION: ${{ github.event.client_payload.workflow_run.conclusion }}
            run: echo "Provider run $CONCLUSION, says: $GREETING"

  3. Request access. Go to Directory → Browse Directory, find the service, choose Request access, pick your consumer repository as the Target Repository, and choose Send Request. Details.

3. Approve and send

Section titled “3. Approve and send”

  1. Approve the request. Signed in as the provider account, go to Provider → Access, filter Pending, and choose Approve Access.

  2. Run the provider workflow. In the provider repository on GitHub, go to Actions → Hello Zekt → Run workflow.

  3. Watch it arrive. When the provider run completes, Zekt sends the event. In the consumer repository, On hello-zekt runs and prints the greeting. In Zekt, Provider → Delivery Status shows the delivery move to Completed.

Didn’t work?

Section titled “Didn’t work?”

See Troubleshooting. The usual causes are an event type that doesn’t match types, or a workflow that isn’t on the default branch.

Next steps

Section titled “Next steps”