mikemcquaid/hookhand

:arrow_right_hook: Runs scripts from webhooks.

HookHand

HookHand is a small web application which runs scripts from webhooks.

Features

• Runs scripts from a cloned Git repository or local directory.
• Runs script and passes parameters based on URL path.
• Webhook metadata can be passed through POSTed JSON or form data and is exposed to the script as environment variables.
• Script output is returned as plain text.
• HTTP status code set based on script exit code.
• Run scripts in the background with ?background=1.

Usage

To use locally run:

git clone https://github.com/mikemcquaid/HookHand
cd HookHand
bundle install
SCRIPTS_GIT_REPO="..." foreman start

Alternatively, to deploy to Heroku click:

Example

1. Run SCRIPTS_GIT_REPO=https://github.com/mikemcquaid/HookHandTestScripts foreman start to start the application and download the HookHandTestScripts repository.
2. Access http://localhost:5000/test/a/b/c and see that it is running the test script and passing parameters a b c.
3. Deploy to a server and set up a webhook with http://yourserver/test/a/b/c as the Payload URL and see that the webhook variables are exported in the format e.g. HOOKHAND_REPOSITORY_CREATED_AT=1412962305. If it's a private repository set the username and password with the SCRIPTS_GIT_USERNAME and SCRIPTS_GIT_PASSWORD environment variables (or set SCRIPTS_GIT_PASSWORD to a personal access token).

Configuration Environment Variables

• REQUEST_TIMEOUT: the number of seconds a script is allowed to run for before being killed. Defaults to 25.
• SCRIPTS_DIR: a path to the directory either storing the scripts or a destination to clone SCRIPTS_GIT_REPO into. Defaults to ./scripts/ relative to the working directory.
• SCRIPTS_GIT_REPO: the Git repository to clone for scripts.
• SCRIPTS_GIT_USERNAME: the HTTP username for accessing a private Git repository.
• SCRIPTS_GIT_PASSWORD: the HTTP password for accessing a private Git repository. Alternatively, a GitHub personal access token.
• WEB_CONCURRENCY: the number of Unicorn (web server) processes to run.

Status

The above features are implemented. Will fix bugs that come along but want to avoid scope-creep.

Contact

Mike McQuaid

License

HookHand is licensed under the MIT License. The full license text is available in LICENSE.txt.

hookhand's Issues

bi-directional synchronization

Moved here from git-multimail/git-multimail#109

I don't know if the final result will be a code change to HookHand, some additional docs, a separate project, or simply a conclusion that it is a bad idea.

For context, the Apache Software Foundation has a bunch of git repositories: https://git-wip-us.apache.org/repos/asf; many are mirrored here: https://github.com/apache/.

Mirroring in this case means that pushes to the asf repository cause the content to appear on github.

I'd like to make that bidirectional. By that I mean that in addition to the above, pushes that happen to github (either explicitly or implicitly by merging pull requests) cause content to appear in the asf repository.

On a project that only sees dozens of pushes per day, where most users primarily use the same copy, where much work occurs on discrete branches, where both machines are generally up, and where synchronization is a matter of seconds; problems with be rare. Rare, but not nonexistent. It is important, therefore, for things to be set up to ensure that when problems occur that the appropriate people are notified so that the problems can be addressed.

If needed, I can go into more details as to why the ASF feels it needs a live copy. I doubt I need to explain why people find the GitHub user interface attractive :-). But I recommend that we simply take that as a given for now, and focus on what the technical challenges would be to address this.