github-build-hook v0.5.0

GitHub Build Hook

A server runs on Node.js that handles your GitHub webhook requests. Automatically run your build and deploy scripts.

Attention: If you are running GitHub Build Hook with a repository can be reached by several person or will be in the future, we strongly recommend that you SHOULD NOT store any personal data in .gh-hookrc configuration file. Even if your delete it from your repository, there is still some possibilities that it can be recovered through commit history. The best practice is to use a bot account that has readonly access to your repository. Its credential is safe to spread within your organization.

TOC

• Install install this CLI tool globally on your host server.
• Usage a brief document github-build-hook.
  • Commands commands of the tool.
  • Configuration introduction of the .gh-hookrc configuration file.
  • Log log file structure.
• License open source license.

Install

There are two ways of installing GitHub Build Hook on your machine.

Prerequisite

• git must be installed on your host machine.
• A public IP address. So GitHub can access your host server.

Also, you need to pay attention that your chained scripts should be specific to your host machine's operating system.

NPM (Recommend)

npm install -g github-build-hook

NPM with Git

npm install -g https://github.com/DevChache/github-build-hook.git

After these two steps, this CLI tool will be available through: 'github-build-hook' in your terminal.

Usage

This section contains basic usage guides for github-build-hook.

Commands

$ help

Help is used to display some detailed introduction of a specific command.

usage:

github-build-hook help command

$ init

This command will initialize your workspace with a clone of your remote repository.

usage:

github-build-hook init path/to/your/workspace

Then, CLI will ask you several questions about your setups. After all things done, there will be a clone of your GitHub repo. under path/to/your/workspace/ directory. Change to that directory, you should find a file named .gh-hookrc. It is the configuration file. It is recommend to keep it in .gitignore unless you insist to put in your repository.

options

-s, --suppress

$ remove

Remove configuration (properties) or clear whole workspace.

usage:

github-build-hook remove type -d path/to/workspace

Available "type"s are:

• all: Replace everything in configuration file without deleting it.
• credential: Remove stored credential in configuration file.
• repository: Remove the whole workspace if it has .ghb-hookrc configuration file.
• delete: Remove the .ghb-hookrc file.

options:

-d, --directory Specify which directory to search.

$ run

This command also has a path parameter, but it is a little different.

usage:

github-build-hook run path/to/your/workspace/repository-dir/ [options]

options:

-q, --quiet This command will start hook server instantly with your configuration file without asking you any questions/confirmations (GitHub bot account credential is still needed). If your configuration is not correct, the startup may fail.

miscellaneous

• Display current version

github-build-hook -v
github-build-hook --version

Configuration

This section will give a brief introduction of .gh-hookrc file by template.

{
    "secret": "secret-for-github-webhook-security", 
    "port": 8080,
    "triggerPhrase": "a trigger phrase in your commit message",
    "tls": false,
    "repoType": "custom|npm",
    "chain": [
        "an array of shell/cmd commands",
        "only available when repoType is custom"
    ],
    "github": {
        "owner": "username/organization",
        "repository": "repository name",
        "username":"bot username",
        "password":"bot password"
    }
}

Security Notes: .github.username and .github.password are visible to everyone that has access to this file. So, if you are using your personal account, never commit this .ghb-hookrc file to a public repository. You are strongly suggested to use a bot account that may have READ ACCESS ONLY to your repository.

Log

The syntax of log file .gh-hook.webhooklog (will be created once a payload received by host server).

Attention: this file is not added to .gitignore automatically. If your bot also syncs data to GitHub repo., make sure to add it to the ignore list.

>>>>>> {event name}: {x-github-delivery} at {timestamp}
{} // payload content
<<<<<<

License

MIT License