README

Gitlab webhook in PHP

This is a very simple webhook for gitlab, allowing to start bash scripts as a reaction to BUILD, PUSTH and TAG events.

Installation

Install with composer:

composer create-project dtforce/slim-hook

Or by cloning this repo.

Configuration

Create a file local.yaml in the config folder containing something like this:

settings:
  secret: 3219874514564 - this should match your webhook secret token
scripts:
  gitlab-org/gitlab-test: - name of the project
    deploy: - what event do we react to
      staging: bash /path/to/app/test.bash deploy - on deploy, what enviroment do we consider
    push:
      refs/heads/master: - on push, what branch do we consider
        cwd: /path/to/app - optional you can set working directory
        - bash /path/to/app/test.bash push - this is going to be executed throug shell_exec
    tag:
        - bash /path/to/app - on tag no subcategories
        - bash do-smothin-else - you can execute multiple commands with one hook
  gitlab-org/gitlab-something-else: - more projects

Variables

When is your script being executed, there are few variables, given to the environment.

These are examples, it should be quite clear:

Deploy

[
    'HOOK_PROJECT_PATH' => 'gitlab-org/gitlab-test',
    'HOOK_BUILD_ID' => 379,
    'HOOK_BUILD_REF' => 'bcbb5ec396a2c0f828686f14fac9b80b780504f2',
    'HOOK_ENV_NAME' => 'staging'
]

Push

[
    'HOOK_PROJECT_PATH' => 'gitlab-org/gitlab-test',
    'HOOK_REF' => 'refs/heads/master',
    'HOOK_BRANCH' => 'master',
    'HOOK_BUILD_REF' => 'da1560886d4f094c3e6c9ef40349f7d38b5d27d7'
]

Tag

[
    'HOOK_PROJECT_PATH' => 'jsmith/example',
    'HOOK_REF' => 'refs/tags/v1.0.0',
    'HOOK_TAG' => 'v1.0.0',
    'HOOK_BUILD_REF' => '82b3d5ae55f7080f1e6022629cdb57bfae7cccc7'
]

Launching

You can configure Apache in the usual way, or you can launch using PHP embedded server like this:

/usr/bin/php7.0 -S localhost:8080 -t /path/to/app/slim-hook/public

BashREST

For convenience this application can also serve simple REST requests. This can be handy, when you want a result of the script executed on the target platform when deploying in gitlab CI. By making request to this server in the following form:

POST to /groupName/projectName/action

you will launch a script described in the config like this:

bashREST:
  groupName/projectName:
    action: launch some bash command here
    action2:
      cwd: dir
      0: test1
      1: test2

If you sent some data (in the form of JSON) in the POST body, the script will receive them in its enviroment variables in a flattened form.

Example:

{
    "test" : "asd",
    "nested" : {
        "a" : "b",
        "asd" : "c"
    },
    "array" : ["asd", "zxc", "xcvxcv"]
}

sent as POST to /bash-rest/test-app/my-action

Will result in these environment variables set:

HOOK_PROJECT_PATH=bash-rest/test-app
HOOK_ACTION=my-action
HOOK_test=asd
HOOK_nested_a=b
HOOK_nested_asc=c
HOOK_array_0=asd
HOOK_array_1=zxc
HOOK_array_2=xcvxcv

If you set-up your secret in the config script, request to the BashREST server will need to authorize themselves with this secret. Secret is stored in header field X-Secret. Notice it is different to the one used by Gitlab Webhooks.

Example of a BashREST call

Suppose config:

bashREST:
  groupName/projectName:
    deploy: echo Application $HOOK_PROJECT_PATH action $HOOK_ACTION called with ENV set to $HOOK_ENV

and assume, shell_exec launches sh or bash, then call the action like this:

curl -X POST http://localhost:4000/groupName/projectName/deploy -H \
    "X-Secret: $BASH_REST_SECRET" -H 'Content-Type: application/json' -d '{"ENV":"production"}'

The response will be returned as application/text containing result(written to stdout) of the executed command:

Application groupName/projectName action deploy called with ENV set to production

The idea is to have something like RPC for bash over HTTP protocol.

That's all

Hope you like it!

dtforce / slim-hook

Maintainers

Details