diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 107 |
1 files changed, 51 insertions, 56 deletions
@@ -1,93 +1,88 @@ # What is it? -GitAutoDeploy.py consists of a small HTTP server that listens for Web hook requests sent from GitHub, GitLab or Bitbucket servers. This application allows you to continuously and automatically deploy you projects each time you push new commits to your repository.</p> +Git-Auto-Deploy consists of a small HTTP server that listens for Web hook requests sent from GitHub, GitLab or Bitbucket servers. This application allows you to continuously and automatically deploy you projects each time you push new commits to your repository.</p>  # How does it work? -When commits are pushed to your Git repository, the Git server will notify ```GitAutoDeploy.py``` by sending a HTTP POST request with a JSON body to a pre configured URL (your-host:8001). The JSON body contains detailed information about the repository and what event that triggered the request. GitAutoDeploy.py parses and validates the request, and if all goes well it issues a ```git pull```. +When commits are pushed to your Git repository, the Git server will notify ```Git-Auto-Deploy``` by sending a HTTP POST request with a JSON body to a pre configured URL (your-host:8001). The JSON body contains detailed information about the repository and what event that triggered the request. ```Git-Auto-Deploy``` parses and validates the request, and if all goes well it issues a ```git pull```. -Additionally, ```GitAutoDeploy.py``` can be configured to execute a shell command upon each successful ```git pull```, which can be used to trigger custom build actions or test scripts.</p> +Additionally, ```Git-Auto-Deploy``` can be configured to execute a shell command upon each successful ```git pull```, which can be used to trigger custom build actions or test scripts.</p> # Getting started + ## Dependencies * Git (tested on version 2.5.0) * Python (tested on version 2.7) -## Configuration +## Install from repository (recommended) + +### Download and install + + git clone https://github.com/olipo186/Git-Auto-Deploy.git + cd Git-Auto-Deploy + +### Configuration + +Make a copy of the sample configuration file and modify it to match your project setup. [Read more about the configuration options](./docs/Configuration.md). + + cp config.json.sample config.json + +*Tip:* Make sure that the path specified in ```pidfilepath``` is writable for the user running the script, as well as any other path configured for your repositories. + +### Running the application + +Run the application my invoking ```python``` and referencing the ```gitautodeploy``` module (the directory ```Git-Auto-Deploy/gitautodeploy```). + + python gitautodeploy -* Copy ```GitAutoDeploy.conf.json.example``` to ```GitAutoDeploy.conf.json``` -* Modify ```GitAutoDeploy.conf.json``` to match your project setup -* Make sure that the ```pidfilepath``` path is writable for the user running the script, as well as any other path configured for your repositories. -* If you don't want to execute ```git pull``` after webhook was fired, you can leave field ```"path"``` empty. +### Start automatically on boot -See the [Configuration](./docs/Configuration.md) documentation for more details. +The easiest way to configure your system to automatically start ```Git-Auto-Deploy``` after a reboot is using crontab. Open crontab in edit mode using ```crontab -e``` and add the entry below. -### Logging + @reboot /usr/bin/python /path/to/Git-Auto-Deploy/gitautodeploy --daemon-mode --quiet --config /path/to/git-auto-deploy.conf.json -To start logging you can define ```"logfilepath": "/home/hermes/gitautodeploy.log"```. Note that you can`t see triggered command output when log is defined, only script output. If you leave ```"logfilepath"``` empty - everething will work as usual (without log). +*Tip:* You can also configure ```Git-Auto-Deploy``` to start automatically using a init.d-script (for Debian and Sys-V like init systems) or a service for systemd. [Read more about starting Git-Auto-Deploy automatically using init.d or systemd](./docs/Start automatically on boot.md). -## Running the application -```python GitAutoDeploy.py``` +## Alternative installation methods + +* [Install as a python module (experimental)](./docs/Install as a python module.md) +* [Install as a debian package (experimental)](./docs/Install as a debian package.md) +* [Start automatically on boot (init.d and systemd)](./docs/Start automatically on boot.md) ## Command line options +Below is a summarized list of the most common command line options. For a full list of available command line options, invoke the application with the argument ```--help``` or read the documentation article about [all avaialble command line options, environment variables and config attributes](./docs/Configuration.md). + 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 ---ssh-keygen | GAD_SSH_KEYGEN | | Scan repository hosts for ssh keys ---force | GAD_FORCE | | Kill any process using the configured port --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 -## Start automatically on boot - -### Crontab -The easiest way to configure your system to automatically start ```GitAutoDeploy.py``` after a reboot is through crontab. Open crontab in edit mode using ```crontab -e``` and add the following: - -```@reboot /usr/bin/python /path/to/GitAutoDeploy.py --daemon-mode --quiet``` - -### Debian and Sys-V like init system. - -* Copy file ```initfiles/debianLSBInitScripts/gitautodeploy``` to ```/etc/init.d/``` -* Make it executable: ```chmod 755 /etc/init.d/gitautodeploy``` -* Also you need to make ```GitAutoDeploy.py``` executable (if it isn't already): ```chmod 755 GitAutoDeploy.py``` -* This init script assumes that you have ```GitAutoDeploy.py``` installed in ```/opt/Git-Auto-Deploy/``` and that the ```pidfilepath``` config option is set to ```/var/run/gitautodeploy.pid```. If this is not the case, edit the ```gitautodeploy``` init script and modify ```DAEMON```, ```PWD``` and ```PIDFILE```. -* Now you need to add the correct symbolic link to your specific runlevel dir to get the script executed on each start up. On Debian_Sys-V just do ```update-rc.d gitautodeploy defaults``` - -### Systemd - -* Copy file ```initfiles/systemd/gitautodeploy.service``` to ```/etc/systemd/system``` -* Also you need to make ```GitAutoDeploy.py``` executable (if it isn't already): ```chmod 755 GitAutoDeploy.py``` -* And also you need to create the user and the group ```www-data``` if those not exists ```useradd -U www-data``` -* This init script assumes that you have ```GitAutoDeploy.py``` installed in ```/opt/Git-Auto-Deploy/```. If this is not the case, edit the ```gitautodeploy.service``` service file and modify ```ExecStart``` and ```WorkingDirectory```. -* now reload daemons ```systemctl daemon-reload``` -* Fire it up ```systemctl start gitautodeploy``` -* Make is start on system boot ```systemctl enable gitautodeploy``` - -## Configure GitHub - -* Go to your repository -> Settings -> Webhooks and Services -> Add webhook</li> -* In "Payload URL", enter your hostname and port (your-host:8001) -* Hit "Add webhook" +## Getting webhooks from git +To make your git provider send notifications to ```Git-Auto-Deploy``` you will need to provide the hostname and port for your ```Git-Auto-Deploy``` instance. Instructions for the most common git providers is listed below. -## Configure GitLab -* Go to your repository -> Settings -> Web hooks -* In "URL", enter your hostname and port (your-host:8001) -* Hit "Add Web Hook" +**GitHub** +1. Go to your repository -> Settings -> Webhooks and Services -> Add webhook</li> +2. In "Payload URL", enter your hostname and port (your-host:8001) +3. Hit "Add webhook" -## Configure Bitbucket -* Go to your repository -> Settings -> Webhooks -> Add webhook -* In "URL", enter your hostname and port (your-host:8001) -* Hit "Save" +**GitLab** +1. Go to your repository -> Settings -> Web hooks +2. In "URL", enter your hostname and port (your-host:8001) +3. Hit "Add Web Hook" -# Example workflows +**Bitbucket** +1. Go to your repository -> Settings -> Webhooks -> Add webhook +2. In "URL", enter your hostname and port (your-host:8001) +3. Hit "Save" -## Continuous Delivery via Pull requests (GitHub only) +# More documentation -It's possible to configure Git-Auto-Deploy to trigger when pull requests are opened or closed on GitHub. To read more about this workflow and how to configure Git-Aut-Deploy here: [Continuous Delivery via Pull requests](./docs/Continuous Delivery via Pull requests.md) +[Have a look in the *docs* directory](./docs), where you'll find more detailed documentation on configurations, alternative installation methods and example workflows. |