gift

A push, and what it runs

The oldest of the triggers is a GitHub push. That hook is a repository, the branches worth answering, a script, and the folder that script runs in. A delivery arrives and every hook watching that repository and that branch runs. Pick a push and watch it land:

The secret is checked before any of that: a delivery whose signature does not add up is refused. gift create can make the webhook on GitHub for you with gh, and then asks GitHub back whether it is really there — a hook in your file that GitHub never calls is worth being told about rather than assumed to work.

Four things a hook can be built on

A hook is two halves: a trigger that says what has to happen, and a script to run when it does. gift triggers lists the four, gift create asks which one this hook is, and every question after that follows from the answer.

github

A push to a repository you named, delivered to a port of your own and checked against the webhook secret before anything runs.

clipboard

The clipboard changing — or changing to something that contains, equals or matches what you said. The content reaches the script in GIFT_CLIPBOARD, and what a pattern captured in GIFT_MATCH_1 and up.

website

A page polled on an interval, firing when it changes, when it matches, or every time. A page behind a login is still a page worth watching: the hook carries the cookies, storage values and headers a browser would send, and a refresh block tells gift which answer means expired and where the new token is — it renews, polls again, and writes the rotated value back itself.

file

A path or a pattern — *.yml, **/*.js — watched for files added, changed or deleted. A burst of writes settles into one run, and the list of what moved is handed to the script in GIFT_FILES_FILE.

What was already there when the server started counts as nothing: restarting re-fires no hook. Each hook keeps its own books under logs/hooks/<name> — a line per request in hook.log, fired, quiet or failed, and an error.log that only exists once something has gone wrong, which is what makes one showing up worth noticing. A trigger is also just a folder: drop one into triggers/ with an index.js and it earns its place in gift create, config.json and gift list.

The server

The port also carries a page of its own: the hooks as they are configured, and the last day of whatever happened — a delivery, a clipboard change, a page that came back different, a file that was written — newest first, with what each one's script printed, filling in while it is still printing it. Anything that looks like a credential is redacted before it is shown.

The other things it does

The same command runs a small set of git chores. gift help lists them, gift run opens a picker — a cursor to move, enter to run, a number key to run that row straight away — and gift <name> skips the picker. Enough of a name will do, and anything after it is passed on to the function itself.

One file of settings

Every setting is in one file — config.json, beside the code. gift config opens it in your editor. Three kinds of section, and which one a setting belongs in follows from who reads it: gift's own are at the top level, each trigger's under triggers.<type>, each function's under functions.<name>:

{
    "pm2_name": "gift",
    "port": 3999,
    "triggers": {
        "github": { "github_webhook_secret": "…", "webhook_url": "…" },
        "website": { "interval": 60000 }
    },
    "functions": {
        "repo-master": { "repo_root": "/Users/me/projects" },
        "weekly-prs": { "repos": "owner/repo1,owner/repo2", "author": "octocat" }
    }
}

It is written on first use with the settings worth looking at already in it, at their defaults, so opening it shows what there is to set rather than a blank page. Each one is declared in a config.schema.json next to the code that reads it — where its default, its description and the environment variable it reaches a script as all come from. A value already in the environment wins over the file, and a flag wins over both. The file is git-ignored and written 0600, because the webhook secret is in it — and hooks.json is treated the same way, because a website hook may be holding a login.

Getting it

curl -fsSL https://raw.githubusercontent.com/lhypds/gift/master/get.sh | bash

1. Install it — the line above. It asks for the public URL that GitHub will deliver to, which is the one thing it cannot work out for itself.
2. gift config — the port to listen on, and the webhook secret to check deliveries against.
3. gift create — first which trigger, then what that trigger needs. For GitHub: the repository, the branches, the script and where to run it. Answer yes and gh makes the webhook on GitHub for you; answer no and you add it yourself under Settings ▸ Webhooks, with the same secret.
4. gift serve — and the next push runs it. gift log to watch it happen.

~/.gift/uninstall.sh takes the gift command back off again, and deleting ~/.gift removes the rest; from a checkout it is ./uninstall.sh.