git middleware for Caddy
MIT License
Middleware for Caddy.
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.)
git repo [path]
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 path] {
repo repo
path path
branch branch
key key
interval interval
clone_args args
pull_args args
hook path secret
hook_type type
then command [args...]
then_long command [args...]
}
{latest}
is a placeholder for latest tag which ensures the most recent tag is always pulled.git clone
e.g. --depth=1
. git clone
is called when the source is being fetched the first time.git pull
e.g. -s recursive -X theirs
. git pull
is used when the source is being updated.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.
A webhook is an interface between a git repository and an external server. On Github, the simplest webhook makes a request to a 3rd-party URL when the repository is pushed to. You can set up a Github webhook at github.com/[username]/[repository]/settings/hooks
, and a Travis webhook in your .travis.yml
. Make sure your webhooks are set to deliver JSON data!
The JSON payload should include at least a ref
key, but all the default supported webhooks will handle this for you.
The hook URL is the URL Caddy will watch for requests on; if your url is, for example /__github_webhook__
and Caddy is hosting https://example.com
, when a request is made to https://example.com/__github_webhook__
Caddy will intercept this request and check that the secret in the request (configured wherever you configure your webhooks) and the secret in your Caddyfile match. If the request is valid, Caddy will git pull
its local copy of the repo to update your site as soon as you push new data. It may be useful to then use a post-merge script or another git hook to rebuild any needed files (updating SASS styles and regenerating Hugo sites are common use-cases), although the then
parameter can also be used for simpler cases.
Note that because the hook URL is used as an API endpoint, you shouldn't have any content / files at its corresponding location in your website.
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
}
You might need quotes "secret-password"
around your secret if it contains any special characters, or you get an error.
Generic webhook payload: <branch>
is branch name e.g. master
.
{
"ref" : "refs/heads/<branch>"
}