Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/fooker/pullomatic

Automated git pulls
https://github.com/fooker/pullomatic

automation git linux trigger webhook

Last synced: 2 months ago
JSON representation

Automated git pulls

Awesome Lists containing this project

README 

        
`pullomatic` automates GIT repository synchronisation.



[![Build Status](https://travis-ci.org/fooker/pullomatic.svg?branch=master)](https://travis-ci.org/fooker/pullomatic)



Storing configuration or other application data in a GIT repository is a common practice.

Usually custom scripts are used to pull updates from remote from time to time.

`pullomatic` replaces these scripts with pure configuration.



Beside the polling interval, `pullomatic` provides a HTTP endpoint which can be used to trigger updates by web-hooks.



Whenever a change is detected in the remote repository branch, the new branch head will be checked out to the path.



## Features



* One configuration file per repository allowing for easy deployment

* Automatically creates target directory with initial clone

* Runs as daemon and checks repositories by interval without cron / timers

* Can be target for Webhooks supporting [github](https://developer.github.com/webhooks/), [gitlab](https://docs.gitlab.com/ee/user/project/integrations/webhooks.html) and others

* Inline configuration of SSH deploy-keys and credentials 

* Executes scripts and commands after updates



## Build



To build, the following requirements must be installed:

* [rustc](https://www.rust-lang.org) >= 1.25

* [cargo](https://github.com/rust-lang/cargo) >= 0.25



After downloading the sources. the following command is used to build:

```bash

cargo build --release

```



The resulting binary will be placed in `target/release/pullomatic`.



## Configuration



Each repository is configured in a single file which must be placed inside `/etc/pullomatic/`.

The filename is used as repository name and must be formatted as YAML file.



The configuration must contain a `path` which specifies the path where the repository lives locally.

On startup, the existence of the repository will checked.

If the repository does not exists, the remote repository will be cloned to that path.

Second, the config must contain a `remote_url` and a `remote_branch` which specifies the remote URL of the GIT repository and the branch to check out.



### Credentials

The configuration can contain a `credentials` section depending on the transport type used to connect to the remote GIT server.



Usually, the `remote_url` contains a username if one is required to authenticate.

As a fallback, a `username` can be specified in this section.



If the SSH or HTTP(S) transport is used, the section can contain a `password` which is used to authenticate agains the remote server.



For SSH, a key pair can be used as an alternative.

Therefore, a `private_key` must be specified containing the SSH private key (as generated by `ssh-keygen`).

Additionally, a `passphrase` can be specified which is used to unlock the key.

If a `public_key` is given, it will not be derived from the private key, but the given one will be used.



### Interval

The check the repository regularly for changes, the configuration can contain a `interval` section.

If this section is present, it must contain a `interval` parameter, which specifies the interval to poll for changes.

The format of this option allows to specify the interval in multiple ways like `30sec` or `5m` (See [here](https://docs.rs/humantime/1.1.1/humantime/fn.parse_duration.html) for more details).



### Webhook

To make updates as instant as possible, webhooks can be used to trigger update checks.

The `webhook` section can be used to enable webhook support.

If webhook is enabled in at least one repository, `pullomatic` will listen for incoming HTTP `POST` requests.



The `provider` parameter must be set to enable support for one of the following supported  services:



| Provider | Config Value | Remarks |

| -------- | ------------ | ------- |

| GitHub   | `github`     | Only `push` events are supported |

| GitLab   | `gitlab`     | Only `push` events are supported |

| Plain    | `plain`      ||

 

#### GitHub

If the GitHub provider is selected, a `secret` parameter can be given.

The same value must be configured in the GitHub webhook configuration.

 

The `check_branch` parameter controls if the branch in the event must match the `remote_branch` of the repository configuration (enabled by default).



#### GitLab

If the GitLab provider is selected, a `token` parameter can be given.

The same value must be configured in the GitLab webhook configuration.

  

The `check_branch` parameter controls if the branch in the event must match the `remote_branch` of the repository configuration (enabled by default).



#### Plain

If The Plain provider is selected, every `POST` request will trigger an update check. 

 



### Script

Each configuration can include a `on_change` hook option which allows to specify a script which is executed every time the repository has changed.

The script is executed right after the updates has been checked out.

It will be started with the working directory set to the local repository path.



The script is executed using `sh -c` and therefor it can contain arbitrary shell commands over multiple lines.

Buf for complex scripts, it is recommended to store the script externally (maybe in the repository itself) and just call the script inside the hook.



### Overview

The following options are allowed in the configuration:



| Option | Type | Required | Description |

| ------ | ---- | -------- |----------- |

| `path` | `str` | ✓ | Path to the GIT repository on disk |

| `remote_url` | `str` | ✓ | Remote URL of the GIT repository to pull changes from |

| `remote_branch` | `str` | ✓ | The branch to check out and pull changes from |

| `credentials.username` | `str` | | The username to use if none is given by `remote_url` |

| `credentials.password` | `str` | (✓) | The password used to authenticate (required for password authentication) |

| `credentials.private_key` | `str` | (✓) | The private SSH key used to authenticate (required for SSH authentication) |

| `credentials.public_key` | `str` | | The public SSH key matching the private SSH key |

| `credentials.passphrase` | `str` | | The passphrase used to unlock the private SSH KEY|

| `interval.interval` | `str` | | The interval used to check the remote GIT repository for updates |

| `webhook.provider` | `str` | | Can be one of `github`, `gitlab` or `plain` |

| `webhook.secret` | `str` | | Secret used to authenitcate GitLab webhook events (only valid for provider `github`) |

| `webhook.token` | `str` | | Secret used to authenitcate GitLab webhook events (only valid for provider `gitlab`) |

| `webhook.check_branch` | `bool` | | Checks if the event branch matches `remote_branch` (only valid for provider `github` or `gitlab`) |

| `on_change` | `str` | | A script executed every time the repository has changed |



## Running



Just execute the `pullomatic` binary.



The configuration path can be changed by using `-c PATH` or `--config PATH`.

If webhooks are used, the listening address can be changed using `-w ADDR:PORT` or `--webhook-listen ADDR:PORT` (defaults to `locahost:8000`).



## Versioning



We use [SemVer](http://semver.org/) for versioning. For the versions available, see the [tags on this repository](https://github.com/fooker/pullomatic/tags). 



## Authors



* **Dustin Frisch** - *Initial work* - [Dustin Frisch](https://github.com/fooker)



See also the list of [contributors](https://github.com/fooker/pullomatic/contributors) who participated in this project.



## License



This project is licensed under the MIT License - see the [LICENSE.md](LICENSE.md) file for details