Skip to content
git middleware for Caddy
Branch: master
Clone or download
Pull request Compare This branch is 15 commits ahead of abiosoft:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
gitos
gittest
.gitignore
LICENSE
README.md
bitbucket_hook.go
bitbucket_hook_test.go
commands.go
config.json
generic_hook.go
generic_hook_test.go
git.go
git_test.go
gitee_hook.go
gitee_hook_test.go
github_hook.go
github_hook_test.go
gitlab_hook.go
gitlab_hook_test.go
go.mod
go.sum
gogs_hook.go
gogs_hook_test.go
logger.go
os.go
scripts.go
service.go
service_test.go
setup.go
setup_test.go
travis_hook.go
webhook.go

README.md

Fork

This is a fork of caddy-git with a pure Go git to support authentication with tokens, and removed sh dependencies.

See https://blog.nobugware.com/post/2019/deploying-a-website-with-caddy-git-and-kubernetes/ for explanations.

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.

Syntax

puregit repo [path]
  • repo is the URL to the repository; SSH and HTTPS URLs are supported
  • path 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:

puregit [repo path] {
	repo        repo
	path        path
	branch      branch
	interval    interval
	hook        path secret
	hook_type   type
	then        command [args...]
	then_long   command [args...]
  	auth_token   github_token
}
  • repo is the URL to the repository; SSH and HTTPS URLs are supported.
  • path is the path to clone the repository into; default is site root. It can be absolute or relative (to site root).
  • branch is the branch or tag to pull; default is master branch. {latest} is a placeholder for latest tag which ensures the most recent tag is always pulled.
  • auth_token is a token use for authentication; only required for private repositories.
  • interval is the number of seconds between pulls; default is 3600 (1 hour), minimum 5. An interval of -1 disables periodic pull.
  • path and secret are used to create a webhook which pulls the latest right after a push. This is limited to the supported webhooks. secret is currently supported for GitHub, Gitlab and Travis hooks only.
  • type is webhook type to use. The webhook type is auto detected by default but it can be explicitly set to one of the supported webhooks. This is a requirement for generic webhook.
  • command is a command to execute after successful pull; followed by args which are any arguments to pass to the command. You can have multiple lines of this for multiple commands. then_long is for long executing commands that should run in 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.

Webhooks

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.

Supported Webhooks

Examples

Public repository pulled into site root every hour:

puregit github.com/user/myproject

Public repository pulled into the "subfolder" directory in the site root:

puregit github.com/user/myproject subfolder

Private repository pulled into the "subfolder" directory with tag v1.0 once per day:

puregit {
	repo     git@github.com:user/myproject
	branch   v1.0
	path     subfolder
	interval 86400
	auth_token bda561bbff29769ae
}

Generate a static site with Hugo after each pull:

puregit 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:

puregit git@github.com:user/myphpsite {
  auth_token bda561bbff29769ae
}
fastcgi / 127.0.0.1:9000 php

Specifying a webhook:

puregit git@github.com: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>"
}
You can’t perform that action at this time.