You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
344 lines
12 KiB
344 lines
12 KiB
6 years ago
|
# 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) <path> | GAD_CONFIG | | Custom configuration file
|
||
|
|
--pid-file <path> | GAD_PID_FILE | pidfilepath | Specify a custom pid file
|
||
|
|
--log-file <path> | GAD_LOG_FILE | logfilepath | Specify a log file
|
||
|
|
--host <host> | GAD_HOST | host | Address to bind to
|
||
|
|
--port <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](https://developer.github.com/webhooks/securing/) 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;
|
||
|
|
|
||
|
|
```json
|
||
|
|
{
|
||
|
|
...
|
||
|
|
"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.
|
||
|
|
|
||
|
|
```json
|
||
|
|
{
|
||
|
|
...
|
||
|
|
"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;
|
||
|
|
```json
|
||
|
|
{
|
||
|
|
"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.
|
||
|
|
|
||
|
|
```json
|
||
|
|
{
|
||
|
|
...
|
||
|
|
"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:
|
||
|
|
|
||
|
|
```json
|
||
|
|
{
|
||
|
|
"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
|
||
|
|
```json
|
||
|
|
{
|
||
|
|
"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.
|
||
|
|
|
||
|
|
```json
|
||
|
|
{
|
||
|
|
"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`.
|
||
|
|
|
||
|
|
```json
|
||
|
|
{
|
||
|
|
"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.
|
||
|
|
|
||
|
|
```json
|
||
|
|
{
|
||
|
|
"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.
|
||
|
|
|
||
|
|
```json
|
||
|
|
{
|
||
|
|
"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.
|
||
|
|
|
||
|
|
```json
|
||
|
|
{
|
||
|
|
"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
|