GitHub triggers start a run from what happens in a repository. All seven are instant — GitHub tells Bizomate the moment it happens:

  • GitHub · New issue — When an issue is opened.
  • GitHub · New pull request — When a pull request is opened.
  • GitHub · Pull request merged — When a pull request is merged.
  • GitHub · Push to a branch — When commits are pushed.
  • GitHub · New release — When a release is published.
  • GitHub · New star — When someone stars the repository.
  • GitHub · Workflow run finished — When a GitHub Actions run finishes.

Publishing adds a webhook to the repository for you, and nothing needs pasting — see How instant triggers work.

Who can do this

Workspace Admins and Editors, on every plan — GitHub is not a premium connection. Viewers see the trigger and its status but cannot change it.

In GitHub, the person whose token the connection uses must be an admin of the repository — its owner, or an admin in the organisation's repository settings. Adding a webhook needs that; write access is not enough.

Before you start

  • A GitHub connection — see Connect GitHub.
  • The token must be allowed to manage webhooks: for a fine-grained token, Webhooks: Read and write on the repository; for a classic token, repo or admin:repo_hook.

Steps

Set up the trigger:

  1. Open the workflow in the designer and open the trigger picker — Browse all triggers on an empty workflow, or select the trigger and Change how it starts.

  2. Under GitHub, select the event — New issue, say. It reads GitHub · instant. Or type GitHub in Search triggers.

  3. In Connection, choose your GitHub connection — for example Consulace GitHub.

  4. In Repository, choose the repository — Repositories the connection reaches, as owner/name. For example consulace/billing-service.

  5. For Push to a branch: optional, in Only this branch, a branch name — main. Empty takes every branch.

  6. For Workflow run finished: under When it, choose Finishes, Succeeds or Fails.

  7. The panel reads Publishing sets this up in GitHub, and every publish sets it up again. It stays while the workflow is published — switched off, what arrives is ignored — and is taken away when the workflow is deleted or starts another way.

  8. Add the steps, then Publish. Bizomate adds a webhook to the repository for that event.

    The panel reads Waiting for the first event — Make one happen; it appears here within seconds.

Test with a real event:

  1. Make the event happen in the repository — open an issue, push a commit, publish a release.
  2. Within seconds the panel reads Listening — instant — Last event 10:45 · New issue · #42 Invoice totals round wrongly.
  3. On Output, select Use the last event, then Test run.

What the trigger gives

Every GitHub trigger gives repository — owner/name, consulace/billing-service — and sender, the username of whoever did it.

New issue:

Field What it is
number The issue's number — what Update an issue and Add a comment take.
title, body Its title and description.
state open.
url The issue's page on GitHub.
author Who opened it.
labels, assignees Lists of label names and usernames.
createdAt When it was opened.

New pull request and Pull request merged:

Field What it is
number The pull request's number.
title, body Its title and description.
state open, or closed once merged.
url Its page on GitHub.
head, base The branch it comes from and the branch it goes into.
draft, merged, mergeable Whether it is a draft, is merged, and can be merged.
author Who opened it.

Push to a branch:

Field What it is
branch The branch pushed to — main.
pusher Who pushed.
head The commit the branch now points at.
compare A GitHub page comparing before and after.
commits A list, each with id, message, author and url.

New release: tag, name, notes, url and prerelease.

New star: stars — how many stars the repository has now — and starredAt. The person who starred is sender.

Workflow run finished: workflow (the Actions workflow's name), conclusion (success, failure, cancelled and so on), branch, url, runNumber, and event — what started the Actions run, such as push.

Use them in later steps as {{ trigger.number }}, {{ trigger.repository }} and so on.

What happens next

  • Each event starts one run of the live version, in Production, named after it — New issue · #42 Invoice totals round wrongly, Pull request merged · #57 Round GST per line, Push to main · 3 commits, New release · v1.4.0, New star · rohan-mehta, Workflow run finished · Deploy · failure.
  • Each workflow has its own webhook in the repository. You can see it in GitHub under the repository's Settings › Webhooks, sending to Bizomate's address.
  • Every publish sets the webhook up again: Bizomate deletes its old webhook and adds a new one. A webhook deleted in GitHub comes back the next time you publish.
  • Changing to another trigger, or another repository, and publishing — or deleting the workflow — deletes the webhook from the repository.

How Bizomate knows an event is GitHub's

When it adds the webhook, Bizomate gives it a secret of its own, made for that webhook and kept encrypted. GitHub signs every event with it (the X-Hub-Signature-256 header), and Bizomate works the signature out again. An event whose signature does not match is answered 401 — The signature does not match. — and starts nothing. The test event GitHub sends when a webhook is added is answered and starts nothing.

Which events start a run

  • New issue — only when an issue is opened. Editing, labelling, closing or reopening one does not.
  • New pull request — only when one is opened, drafts included. Reopening or marking ready for review does not.
  • Pull request merged — only when a pull request is closed by merging. Closing without merging does not.
  • Push to a branch — every push to a branch, or only pushes to the branch in Only this branch — the exact name, capitals included. Pushing a tag does not, and nor does deleting a branch.
  • New release — when a release is published, pre-releases included. Saving a draft does not; publishing it later does.
  • New star — when someone stars the repository. Removing a star does not.
  • Workflow run finished — when any Actions workflow in the repository finishes. Succeeds takes only success; Fails takes failure and timed_out; Finishes takes every ending, cancelled and skipped included.

Good to know

  • Push to a branch with Only this branch empty also starts a run when a tag is pushed — its branch reads refs/tags/v1.4.0 — and when a branch is deleted, with no commits. Fill in Only this branch to hear one branch only.
  • Merging a pull request is also a push to the branch it went into. Workflows on both triggers both run.
  • Workflow run finished hears every Actions workflow in the repository. To act on one, add an If step on {{ trigger.workflow }}. A run started by Run a workflow counts too.
  • GitHub allows 20 webhooks for one event on a repository. Each published workflow with a GitHub trigger uses one.
  • A call over 256 KB is not taken, so a very large push may not start a run.
  • If someone edits the webhook's secret in GitHub, every event is refused. Publish again to put a new webhook in its place.

If something goes wrong

What you see Why What to do
Not listening — GitHub would not take Bizomate's address: GitHub would not add a webhook to consulace/billing-service: adding one needs admin on the repository, and a token allowed to manage its webhooks. Fix it, then publish again. The token's owner is not an admin of the repository, or a fine-grained token lacks Webhooks: Read and write. Ask a repository admin to make the token, or give the permission. Then publish again.
Not listening — GitHub would not take Bizomate's address: GitHub refused: Bad credentials. Check the connection's details on Connections. Fix it, then publish again. The token has ended or was deleted. Select Reconnect, paste a new token, then publish again.
Not listening — … Repository “…” is not owner/name, like consulace/website. … Repository holds something other than owner/name. Choose it from the list.
Waiting for the first event stays Nothing has happened yet, the event is not one that starts a run (see above), or the branch filter leaves it out. Make the event happen. In GitHub, the webhook's Recent Deliveries show what GitHub sent and Bizomate's answer.
Nothing has arrived yet — make one happen in GitHub, then try again. on Output No event has reached the trigger yet. Make one happen, wait for Listening — instant, then Use the last event.
A run did not start for an event the panel shows The workflow is switched off, or its workspace is archived. Switch it on — see Switch a workflow on or off. The missed event does not run later.