git Addon
git clones a git repository into the site. This makes it possible to deploy your site with a simple git push.
The git directive starts a service routine that runs during the lifetime of the server. When the service starts, it clones the repository. While the server is still up, it pulls the latest every so often. You can also set up a webhook to pull immediately after a push. In regular git fashion, a pull only includes changes, so it is very efficient.
If a pull fails, the service will retry up to three times. If the pull was not successful by then, it won't try again until the next interval.
Requirements: This directive requires git to be installed. Also, private repositories may only be accessed from Linux or Mac systems. (Contributions are welcome that make private repositories work on Windows.)
Syntax
git repo [clonepath]
- repo is the URL to the repository; SSH and HTTPS URLs are supported
- clonepath is the path, relative to site root, to clone the repository into; default is site root
This simplified syntax pulls from master every 3600 seconds (1 hour) and only works for public repositories.
For more control or to use a private repository, use the following syntax:
git repo [clonepath] {
repo repo
path clonepath
branch branch
key key
hook path [secret]
interval interval
then command [args...]
then_longcommand [args...]
}
- repo is the URL to the repository; SSH and HTTPS URLs are supported.
- clonepath is the path, relative to site root, to clone the repository into; default is site root.
- branch is the branch or tag to pull; default is master branch. Can be {latest} for most recent tag.
- key is the path to the SSH private key; only required for private repositories.
- path and secret are used to create a webhook which pulls the latest right after a push. This supports GitHub, GitLab, BitBucket and a generic format for others. secret is currently supported for GitHub hooks only.
- interval is the number of seconds between pulls; default is 3600 (1 hour), minimum 5.
- command is a command to execute after successful pull; followed by args which are any arguments to pass to the command. If multiple "then" lines are used, they will be executed in order.
- then_long is for long-running commands that should run in the background.
Each property in the block is optional. The path and repo may be specified on the first line, as in the first syntax, or they may be specified in the block with other values.
Examples
Public repository pulled into site root every hour:
git github.com/user/myproject
Public repository pulled into the "subfolder" directory in the site root:
git github.com/user/myproject /subfolder
Private repository pulled into the "subfolder" directory with tag v1.0 once per day:
git {
repo [email protected]:user/myproject
branch v1.0
key /home/user/.ssh/id_rsa
path subfolder
interval 86400
}
Generate a static site with Hugo after each pull:
git github.com/user/site {
path ../
then hugo --destination=/home/user/hugosite/public
}
Part of a Caddyfile for a PHP site that gets changes from a private repo:
git [email protected]:user/myphpsite {
key /home/user/.ssh/id_rsa
}
fastcgi / 127.0.0.1:9000 php
Specifying a webhook:
git [email protected]:user/site {
hook /webhook secret-password
}
Generic webhook payload:
{
"ref" : "refs/heads/branch"
}