pullomatic automates GIT repository synchronisation.

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, gitlab 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 >= 1.25
• cargo >= 0.25

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

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 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 for versioning. For the versions available, see the tags on this repository.

Authors

• Dustin Frisch - Initial work - Dustin Frisch

See also the list of contributors who participated in this project.

License

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