12 KiB

Raw Blame History

Command line options and environment variables

Git-Auto-Deploy supports a number of configurable options. Some of them are available using command line options, where others are only configurable from the config file. Below is a list of the options made available from the command line. Every command line option has also a corresponding environment variable. In the cases where a corresponding config file attribute is available, that attribute name is listed.

There is also support for supplying configuration options for up to one repository using environmetn variables. Variable names and descriptios are available in the section (Repository configuration using environment variables)[#eepository-configuration-using-environment-variables].

The list of available command line options can also be seen by invoke the application with the argument --help.

Command line option	Environment variable	Config attribute	Description
--daemon-mode (-d)	GAD_DAEMON_MODE		Run in background (daemon mode)
--quiet (-q)	GAD_QUIET		Supress console output
--config (-c)	GAD_CONFIG		Custom configuration file
--pid-file	GAD_PID_FILE	pidfilepath	Specify a custom pid file
--log-file	GAD_LOG_FILE	logfilepath	Specify a log file
--host	GAD_HOST	host	Address to bind to
--port	GAD_PORT	port	Port to bind to
--ssh-keyscan	GAD_SSH_KEYSCAN		Scan repository hosts for ssh keys and add them to $HOME/.ssh/known_hosts

Configuration file options

The configuration file is formatted according to a JSON inspired format, with the additional feature of supporting inline comments. The possible root elements are as follow:

pidfilepath: The path where pid files are kept.
logfilepath: To enable logging, set this to a valid file path.
log-level: Sets the threshold for the log output. Default value is NOTSET (all details). Recommended value is INFO (less details).
host: What IP address to listen on.
port: The port for the web server to listen on.
global_deploy: An array of two specific commands or path to scripts to be executed for all repositories defined:
- [0] = The pre-deploy script.
- [1] = The post-deploy script.
repositories: An array of repository configurations.

Repositories

Repository configurations are comprised of the following elements:

url: The URL to the repository.
match-url: An alternative URL used when matching incoming webhook requests (see https://github.com/olipo186/Git-Auto-Deploy/pull/148)
branch: The branch which will be checked out.
remote: The name of the remote to use.
path: Path to clone the repository to. If omitted, the repository won't be cloned, only the deploy scripts will be executed.
deploy: A command to be executed. If path is set, the command is executed after a successfull pull.
payload-filter: A list of inclusive filters/rules that is applied to the request body of incoming web hook requests and determines whether the deploy command should be executed or not. See section Filters for more details.
header-filter: A set of inclusive filters/rules that is applied to the request header of incoming web hook requests and determines whether the deploy command should be executed or not. See section Filters for more details.
secret-token: The secret token set for your webhook (currently only implemented for GitHub and GitLab)
prepull: A command to execute immediately before the git pull. This command could do something required for the git pull to succeed such as changing file permissions.
postpull: A command to execute immediately after the git pull. After the prepull command is executed, postpull can clean up any changes made.

Filters

(Currently only supported for GitHub and GitLab)

With filters, it is possible to trigger the deploy only if a set of specific criterias are met. The filter can be applied to the web hook request header (if specified using the header-filter option) or to the request body (payload-filter).

Allow web hooks with specific header values only (header-filter)

Some Git providers will add custom HTTP headers in their web hook requests when sending them to GAD. Using a header-filter, you can configure GAD to only process web hooks that has a specific HTTP header specified.

For example, if you'd like to only process requests that has the X-Event-Key header set to the value pullrequest:fulfilled, you could use the following config;

{
  ...
  "repositories": [
    {
      ...
      "header-filter": {
          "X-Event-Key": "pullrequest:fulfilled"
      }
    }
  ]
}

If a header name is specified but with the value set to true, any request that has the header specified will pass without regard to the header value.

{
  ...
  "repositories": [
    {
      ...
      "header-filter": {
          "X-Event-Key": true
      }
    }
  ]
}

Allow web hooks with specific payload only (payload-filter)

A web hook request typically contains a payload, or a request body, made up of a JSON object. The JSON object in the request body will follow a format choosen by the Git server. Thus, it's format will differ depending on whether you are using GitHub, GitLab, Bitbucket or any other Git provider.

A payload-filter can be used to set specific criterias for which incoming web hook requests should actually trigger the deploy command. Filter can be setup to only trigger deploys when a commit is made to a specific branch, or when a pull request is closed and has a specific destination branch.

Since the format of the payload differs depending on what Git provider you are using, you'll need to inspect the web hook request format yourself and write a filter that matches its structure.

To specify a filter that should be applied further down the object tree, a dot notation (".") is used. For example, if the request body looks like this;

{
  "action": "opened",
  "number": 69,
  "pull_request": {
    "url": "https://api.github.com/repos/olipo186/Git-Auto-Deploy/pulls/69",
    "id": 61793882,
    "html_url": "https://github.com/olipo186/Git-Auto-Deploy/pull/69",
    "diff_url": "https://github.com/olipo186/Git-Auto-Deploy/pull/69.diff",
    "patch_url": "https://github.com/olipo186/Git-Auto-Deploy/pull/69.patch",
    "issue_url": "https://api.github.com/repos/olipo186/Git-Auto-Deploy/issues/69",
    "number": 69,
    "state": "open",
    "locked": false,
    "title": "Refactoring. Fixed some imminent issues.",
    "user": {
      "login": "olipo186",
      "id": 1056476,
      "avatar_url": "https://avatars.githubusercontent.com/u/1056476?v=3",
      "gravatar_id": "",
      ...
  },
  ...
}

You could specify the following filter, which would only trigger on pull requests created by olipo186.

{
  ...
  "repositories": [
    {
      ...
      "payload-filter": [
        {
          "action": "opened",
          "pull_request.user.login": "olipo186"
        }
      ]
    }
  ]
}

Legacy filters (older format)

For example, deploy on push to the master branch only, ignore other branches.

Filters are defined by providing keys/values to be looked up in the original data sent by the web hook.

For example, GitLab web hook data looks like this:

 {
  "object_kind":"build",
  "ref":"master",
  "tag":false,
  ...
 }

A filter can use object_kind and ref attributes for example to execute the deploy action only on a build event on the master branch.

Examples

GitHub

The following example will trigger when a pull request with master as base is closed. The command ./prepull and ./postpull will execute immediately before and after the pull

{
  "host": "0.0.0.0",
  "port": 8080,
  "global_deploy": [
    "echo Pre-deploy script",
    "echo Post-deploy script"
  ],
  "repositories": [
    {
      "url": "https://github.com/olipo186/Git-Auto-Deploy.git",
      "branch": "master",
      "remote": "origin",
      "path": "~/repositories/Git-Auto-Deploy",
      "deploy": "echo deploying",
      "prepull": "chmod u+w config.json",
      "postpull": "chmod u-w config.json",
      "filters": [
        {
            "action": "closed",
            "pull_request": true,
            "pull_request.base.ref": "master"
        }
      ]
    }
  ]
}

GitLab

(Note: the filter examples below are valid for GitLab)

Execute pre-deploy script, don't pull the repository but execute a deploy script, and finish with a post-deploy script. Execute only for push events on the master branch.

{
  "pidfilepath": "~/.gitautodeploy.pid",
  "host": "0.0.0.0",
  "port": 8080,
  "global_deploy": [
    "echo Pre-deploy script",
    "echo Post-deploy script"
  ],
  "repositories": [
    {
      "url": "http://gitlab/playground/hooktest.git",
      "deploy": "echo deploying",
      "filters": [
        {
          "object_kind": "push",
          "ref": "refs/heads/master"
        }
      ]
    }
  ]
}

Clone repository on push to master.

{
  "pidfilepath": "~/.gitautodeploy.pid",
  "host": "0.0.0.0",
  "port": 8080,
  "repositories": [
    {
      "url": "http://gitlab/playground/hooktest.git",
      "branch": "master",
      "remote": "origin",
      "path": "~/repositories/hooktest",
      "filters": [
        {
          "object_kind": "push",
          "ref": "refs/heads/master"
        }
      ]
    }
  ]
}

Execute script upon GitLab CI successful build of master branch.

{
  "pidfilepath": "~/.gitautodeploy.pid",
  "host": "0.0.0.0",
  "port": 8080,
  "global_deploy": [
    "echo Pre-deploy script",
    "echo Post-deploy script"
  ],
  "repositories": [
    {
      "url": "http://gitlab/playground/hooktest.git",
      "deploy": "echo deploying project!",
      "filters": [
        {
          "object_kind": "build",
          "ref": "master",
          "build_status": "success"
        }
      ]
    }
  ]
}

Bitbucket Server

Get source using SSH.

{
  "host": "0.0.0.0",
  "port": 8080,
  "global_deploy": [
    "echo Pre-deploy script",
    "echo Post-deploy script"
  ],
  "repositories": [
    {
      "url": "ssh://git@bitbucket.example.com/KEY/Git-Auto-Deploy.git",
      "match-url": "Git-Auto-Deploy",
      "branch": "master",
      "remote": "origin",
      "path": "~/repositories/Git-Auto-Deploy",
      "deploy": "echo deploying"
    }
  ]
}

Using HTTPS.

{
  "host": "0.0.0.0",
  "port": 8080,
  "global_deploy": [
    "echo Pre-deploy script",
    "echo Post-deploy script"
  ],
  "repositories": [
    {
      "url": "https://bitbucket.example.com/scm/KEY/Git-Auto-Deploy.git",
      "match-url": "Git-Auto-Deploy",
      "branch": "master",
      "remote": "origin",
      "path": "~/repositories/Git-Auto-Deploy",
      "deploy": "echo deploying"
    }
  ]
}


# Repository configuration using environment variables

It's possible to configure up to one repository using environment variables. This can be useful in some specific use cases where a full config file is undesired.

Environment variable | Description
-------------------- | --------------------------
GAD_REPO_URL         | Repository URL
GAD_REPO_BRANCH      |
GAD_REPO_REMOTE      |
GAD_REPO_PATH        | Path to where ```Git-Auto-Deploy``` should clone and pull repository
GAD_REPO_DEPLOY      | Deploy command

12 KiB Raw Blame History