A Cloudflare worker that posts Favro card comments in response to receiving various Github webhook requests.
Inspects incoming webhook requests for references to Favro card IDs (ABC-123
or similar).
If any are detected the worker will then attempt to post a comment to the corresponding
Favro card with a link to the commit/issue/PR/etc. which referenced it.
You'll need node
and
npm
(or another compatible package manager) first.
git clone git@github.com:mogelbrod/github-to-favro.git
cd github-to-favro
npm install # installs the `wrangler` CLI together with remaining dependencies
Installing wrangler
via NPM on ARM Macs is not supported as of October 2022,
instead follow the instructions in
the wrangler repository.
If you do not yet have a Cloudflare account you can sign up for free on https://dash.cloudflare.com/sign-up/workers.
Once you have a Cloudflare account you need to login using the wrangler
CLI:
wrangler login
If you're having trouble with the CLI never retrieving the token
(stuck in infinite polling after issuing the command), then log
out of cloudflare from the web and retry wrangler login
,
or follow these instructions.
You can verify that the auth succeeded using wrangler whoami
.
Use wrangler
to create the worker (same command as updating an existing worker):
wrangler publish
Note down the URL of the created worker - you'll need to provide it when setting up each Github webhook.
The worker requires these environment variables to be defined to function:
FAVRO_PREFIX
: The Favro card ID prefix used to identify cards:
ABC
if card IDs follow the patternABC-123
FAVRO_ORG
: The Favro organization ID, can be determined from the Favro web URL:
https://favro.com/organization/{FAVRO_ORG}/...
FAVRO_AUTH
: Favro API Authentication header for the user to impersonate, including either password (email:password
) or Favro access token (email:access-token
)GITHUB_WEBHOOK_SECRET
: An arbitrary string used to authenticate the incoming Github webhooks
These can quickly be saved to Cloudflare using wrangler
:
wrangler secret put FAVRO_PREFIX
wrangler secret put FAVRO_ORG
wrangler secret put FAVRO_AUTH
wrangler secret put GITHUB_WEBHOOK_SECRET
Once the worker is online you'll need to set up a webhook for each Github
repository that you wish to subscribe to. This can be done from the Github web
UI by navigating to
https://github.com/OWNER/REPO/settings/hooks/new (replace OWNER
& REPO
).
Enter the following in the form:
- Payload URL: URL to the published Cloudflare worker (output when running
wrangler publish
) - Content type:
application/json
- Secret: The value of the
GITHUB_WEBHOOK_SECRET
chosen in Worker secrets - Events to trigger the webhook: everything, or the individual events you're interested in, typically:
pushes, branch/tag creation, all commit/discussion/issue/pull request events, project cards & releases
Once the webhook has been created everything should be set up. You can now try
out the integration by pushing a commit that references an existing Favro card
in the FAVRO_ORG
that is accessible to FAVRO_AUTH
. If everything works then
the worker should post a comment to the card in question within seconds after
the commit is pushed.
The worker is written in TypeScript, and is built & published through wrangler
.
wrangler dev
starts up a locally served version of the worker that is reloaded on local file changes. It actually runs on cloudflares servers, and so has full access to all features (such as secrets and KV namespaces).wrangler publish
will generate a production build of the worker and then deploy it.wrangler tail
will stream logs from the published (live) worker to your terminal.npm start
- alias forwrangler dev
npm run deploy
- alias forwrangler publish
npm run deploy:watch
- watches for changes tosrc/**
, re-runningwrangler dev && wrangler tail
npm test
- runs local "test suite"npm test:watch
- runs local "test suite" wheneversrc/**
changes