Skip to content

desaroger/pm2-hooks

Repository files navigation

pm2-hooks

GitHub version Travis-CI Codeclimate Codeclimate Coverage Dependency DevDependency

PM2 module to listen webhooks from github, bitbucket, gitlab, jenkins and droneci. When a webhook is received you can run a script, pull your project, restart pm2, etc.

This project is highly inspired by vmarchaud/pm2-githook.

Features (changelog):

  • Runs an http server listening for webhooks
  • Works on any repository system, as for now it does nothing with the payload received. In the near future I will check the branch or the action, the secret, etc.
  • Only runs the command you set
  • Run the command in the cwd defined for the app

Wanted features, to be done during Mach/2017:

  • Check payload for secret, check common headers on main git repositories (github, bitbucket, gitlab, etc) to know if is a valid call

Possible features, as I need to think about it:

  • Auto-restart pm2 app after a successful command run
  • Make an automatic git pull on the folder, and make a prePull and postPull available commands (same approach as vmarchaud/pm2-githook)

Install

To install it simply run:

$ pm2 install pm2-hooks

Warning: This library currently (2017 feb 26) is in ALPHA state. This means some things:

  • You can help me a lot making a comment/issue/PR
  • I will try to publish the last version to npm so you can install it with only pm2 install pm2-hooks. If for some reason the version on npm is outdated you always will be capable of run pm2 install desaroger/pm2-hooks to be sure to install the last version directly from the repository.

Usage

Step 1: Prepare the ecosystem file

By default pm2-hooks doesn't do anything. You need to set the key env_hook inside the config of a given app, inside the ecosystem file.

If env_hook isn't defined or is falsy then is disabled.

Example of an ecosystem file:

{
	apps: [
		{
			name: 'api-1',
			script: 'server.js'
		},
		{
			name: 'api-2',
			script: 'server.js',
			env_hook: {
				command: 'git pull && npm i && npm test && pm2 restart api-2',
				cwd: '/home/desaroger'
			}
		}
	]
}

Where api-1 has hook disabled and api-2 is enabled and when the hook is called, the command is executed.

Available options:

  • command {string} The line you want to execute. Will be executed with NodeJS spawn. (optional, but if not set this is not going to do nothing ¯\(ツ)/¯)
  • cwd {string} The cwd to use when running the command. If not set, the one used on your ecosystem app configuration will be used (if set).
  • commandOptions {object} The object that we will pass to the NodeJS spawn. Defaults to a blank object, and later we add the cwd.
  • type {string} [not implemented yet] The git server you are going to use [github, gitlab, bitbucket, etc].

Step 2: Install

If you didn't install before, install it. If you installed it, then you will need to restart it. For that, run pm2 restart pm2-hooks.

Step 3: Try it

Now you have a server on port 9000 by default. You can make a call to http://localhost:9000/api-2 to see the response.

If everything went fine, you will see:

{
	status: 'success',
	message: 'Route "api-2" was found'
	code: 0
}

And the command had been executed.

Step 4: See the log

Everything will be logged in the pm2 logs. For see them, run:

$ pm2 logs pm2-hooks

And for see the entire log:

$ cat ~/.pm2/logs/pm2-hooks-out-0.log

FAQ

How I can change the port?

You can set the port (where the default port is 9000) setting it in the config of the pm2 module. For doing that, run:

$ pm2 set pm2-hooks:port 3000

How I can uninstall it?

You can uninstall this module running:

$ pm2 uninstall pm2-hooks

Another similar projects

These are some projects I found similar to mine. Please let me know if you know anoher.

  • vmarchaud/pm2-githook: From where I was inspired. It works on any repository, pulls the repo when webhook is called and has preHook and postHook commands available.
  • oowl/pm2-webhook: Works on any repository. If you want to use the secret, then the webhook must contain the X-Hub-Signature in order to work (I don't know if every git server contains it).

Copyright and license

Copyright 2017 Roger Fos Soler

Licensed under the MIT License.

About

Webhook server for pm2

Topics

Resources

License

Stars

Watchers

Forks

Packages

No packages published