{"id":15525264,"url":"https://github.com/donatj/hookah","last_synced_at":"2025-04-23T08:47:13.523Z","repository":{"id":11081033,"uuid":"62770968","full_name":"donatj/hookah","owner":"donatj","description":"GitHub Webhooks Made Easy!","archived":false,"fork":false,"pushed_at":"2024-12-01T06:54:08.000Z","size":167,"stargazers_count":32,"open_issues_count":1,"forks_count":3,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-29T23:11:45.914Z","etag":null,"topics":["github-webhooks","hook-manager","hook-script","server"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/donatj.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"custom":"https://www.paypal.me/donatj/15","ko_fi":"donatj","github":"donatj"}},"created_at":"2016-07-07T03:10:40.000Z","updated_at":"2024-12-01T06:54:11.000Z","dependencies_parsed_at":"2024-06-19T01:34:57.903Z","dependency_job_id":"bff6a847-3a1d-4685-989c-ea93a2996b91","html_url":"https://github.com/donatj/hookah","commit_stats":{"total_commits":140,"total_committers":6,"mean_commits":"23.333333333333332","dds":"0.16428571428571426","last_synced_commit":"6b775bac56e01aa85b9b5dcbb3cea0827c04e411"},"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/donatj%2Fhookah","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/donatj%2Fhookah/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/donatj%2Fhookah/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/donatj%2Fhookah/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/donatj","download_url":"https://codeload.github.com/donatj/hookah/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250402061,"owners_count":21424640,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["github-webhooks","hook-manager","hook-script","server"],"created_at":"2024-10-02T10:56:08.759Z","updated_at":"2025-04-23T08:47:13.492Z","avatar_url":"https://github.com/donatj.png","language":"Go","funding_links":["https://www.paypal.me/donatj/15","https://ko-fi.com/donatj","https://github.com/sponsors/donatj"],"categories":[],"sub_categories":[],"readme":"# Hookah\n\n[![Join the chat at https://gitter.im/hookah-server/Lobby](https://badges.gitter.im/hookah-server/Lobby.svg)](https://gitter.im/hookah-server/Lobby?utm_source=badge\u0026utm_medium=badge\u0026utm_campaign=pr-badge\u0026utm_content=badge)\n\n[![Go Report Card](https://goreportcard.com/badge/github.com/donatj/hookah/v3)](https://goreportcard.com/report/github.com/donatj/hookah/v3)\n[![GoDoc](https://godoc.org/github.com/donatj/hookah/v3?status.svg)](https://godoc.org/github.com/donatj/hookah/v3)\n[![CI](https://github.com/donatj/hookah/actions/workflows/ci.yml/badge.svg)](https://github.com/donatj/hookah/actions/workflows/ci.yml)\n\nHookah is a simple server for GitHub Webhooks that forwards the hooks message to any series of scripts, be they PHP, Ruby, Python or even straight up shell.\n\nIt simply passes the message on to the STDIN of any script.\n\n## Installation\n\n### From Source\n\nBuilding v3 requires Go 1.20+\n\n```bash\ngo install github.com/donatj/hookah/v3/cmd/hookah@latest\n```\n\n### From Binary\n\nsee: [Releases](https://github.com/donatj/hookah/releases).\n\n## Basic Usage\n\nWhen receiving a Webhook request from GitHub, Hookah checks `{server-root}/{vendor}/{repo}/{X-GitHub-Event}/*` for any ***executable*** scripts, and executes them sequentially passing the JSON payload to it's standard in.\n\nThis allows actual hook scripts to be written in any language you prefer.\n\nFor example, a script `server/donatj/hookah/push/log.rb` would be executed every time a \"push\" event Webhook was received from GitHub on the donatj/hookah repo.\n\n## Example Hook Scripts\n\n### bash + [jq](https://stedolan.github.io/jq/)\n\n```bash\n#!/bin/bash\n\nset -e\n\njson=`cat`\nref=$(\u003c\u003c\u003c \"$json\" jq -r .ref)\n\necho \"$ref\"\nif [ \"$ref\" == \"refs/heads/master\" ]\nthen\n        echo \"Ref was Master\"\nelse\n        echo \"Ref was not Master\"\nfi\n\n```\n\n### PHP\n\n```php\n#!/usr/bin/php\n\u003c?php\n\n$input = file_get_contents(\"php://stdin\");\n$data  = json_decode($input, true);\n\nprint_r($data);\n\n```\n\n### Note\n\nDon't forget your scripts need to be executable. This means having the executable bit set ala `chmod +x \u003cscript filename\u003e`, and having a [shebang](https://en.m.wikipedia.org/wiki/Shebang_(Unix)) pointing to your desired interpreter, i.e. `#!/bin/bash`\n\n## Documentation\n\nStandard input (stdin) contains the unparsed JSON body of the request.\n\n### Execution\n\nThe server root layout looks like `{server-root}/{vendor}/{repo}/{X-GitHub-Event}/{script-name}`\n\nScripts are executed at each level, in order of least specific to most specific. At an individual level, the execution order is **file system specific** and *must not* be depended upon.\n\nA directory at the vendor or repo level named `@@` will behave as a wildcard. As such a file named `server-root/donatj/@@/pull_request_review_comment/script.sh` would execute for all of @donatj's `pull_request_review_comment` events regardless of repo.\n\n### Error Handling\n\nError handlers are scripts prefixed with `@@error.` and function similarly to standard scripts. Error handlers however are only triggered when the executiono of a normal script returns a **non-zero** exit code.\n\nError handlers like normal scripts trigger in order up from the root to the specificity level of the script.\n\n### Example\n\nConsider the following server file system.\n\n```\n├── @@error.rootlevel.sh\n├── run-for-everything.sh\n└── donatj\n    ├── @@error.userlevel.sh\n    ├── run-for-donatj-repos.sh\n    ├── @@\n    │   └── pull_request_review_comment\n    │       └── all-of-donatjs-pr-comments.sh\n    └── hookah\n        └── pull_request_review_comment\n            ├── @@error.event-level.sh\n            ├── likes-to-fail.sh\n            └── handle-review.php\n```\n\nThe execution order of a `pull_request_review_comment` event is as follows:\n\n```\nrun-for-everything.sh\ndonatj/run-for-donatj-repos.sh\ndonatj/hookah/pull_request_review_comment/likes-to-fail.sh\ndonatj/hookah/pull_request_review_comment/handle-review.php\ndonatj/@@/pull_request_review_comment/all-of-donatjs-pr-comments.sh\n```\n\nNow let's consider if `likes-to-fail.sh` lives up to it's namesake and returns a non-zero exit code. The execution order then becomes:\n\n```\nrun-for-everything.sh\ndonatj/run-for-donatj-repos.sh\ndonatj/hookah/pull_request_review_comment/likes-to-fail.sh\n@@error.rootlevel.sh\n@@error.userlevel.sh\n@@error.event-level.sh\ndonatj/hookah/pull_request_review_comment/handle-review.php\ndonatj/@@/pull_request_review_comment/all-of-donatjs-pr-comments.sh\n```\n\nIn contrast, imagining `donatj/run-for-donatj-repos.sh` returned a non-zero status, the execution would look as follows:\n\n```\nrun-for-everything.sh\ndonatj/run-for-donatj-repos.sh\n@@error.rootlevel.sh\n@@error.userlevel.sh\ndonatj/hookah/pull_request_review_comment/likes-to-fail.sh\ndonatj/hookah/pull_request_review_comment/handle-review.php\ndonatj/@@/pull_request_review_comment/all-of-donatjs-pr-comments.sh\n```\n\n### Environment Reference\n\n#### All Executions\n\n`GITHUB_EVENT` : The contents of the `X-Github-Event` header.\n\n`GITHUB_DELIVERY` : The contents of the `X-GitHub-Delivery` header. A Unique ID for the Given Request\n\n`GITHUB_LOGIN` : The GitHub login of the owner of the repository.\n\n`GITHUB_REPO` : The name portion of the repository, e.g. `hookah`.\n\n`GITHUB_ACTION` : The action of the event, e.g. `opened`.\n\n`HOOKAH_SERVER_ROOT` : The absolute path of the root directory of the hookah server.\n\n#### Error Handler Executions\n\n`HOOKAH_EXEC_ERROR_FILE` : The path to the executable that failed to execute.\n\n`HOOKAH_EXEC_ERROR` : The error message received while trying to execute the script.\n\n`HOOKAH_EXEC_EXIT_STATUS` : The exit code of the script. This may **not** be defined in certain cases where execution failed entirely.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdonatj%2Fhookah","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdonatj%2Fhookah","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdonatj%2Fhookah/lists"}