git

README

git

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 does not chain in a handler. Instead, it starts a service routine that runs during the lifetime of the server. When the server starts, it clones the repository. While the server is still up, it pulls the latest every so often. In regular git fashion, a download 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 [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:

git [repo path] {
	repo        repo
    path        path
	branch      branch
	key         key
	interval    interval
	hook        path secret
	then        command [args...]
	then_long   command [args...]
}

• 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.
• 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.
• key is the path to the SSH private key; only required for private repositories.
• interval is the number of seconds between pulls; default is 3600 (1 hour), minimum 5.
• path and secret are used to create a webhook which pulls the latest right after a push. This is currently limited to Github, Gitlab and BitBucket and a generic format for others. secret is currently supported for GitHub hooks only.
• 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.

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     git@github.com: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 git@github.com:user/myphpsite {
	key /home/user/.ssh/id_rsa
}
fastcgi / 127.0.0.1:9000 php

Specifying a webhook:

git git@github.com:user/site {
	hook /webhook secret-password
}

Generic webhook payload:

{
	"ref" : "refs/heads/branch"
}

Documentation

Index

• Constants
• Variables
• func Init() error
• func Logger() *log.Logger
• func SetLogger(l *log.Logger)
• func SetOS(os gitos.OS)
• func Setup(c *setup.Controller) (middleware.Middleware, error)
• func Start(repo *Repo)
• type BitbucketHook
  • func (b BitbucketHook) DoesHandle(h http.Header) bool
  • func (b BitbucketHook) Handle(w http.ResponseWriter, r *http.Request, repo *Repo) (int, error)
• type GenericHook
  • func (g GenericHook) DoesHandle(h http.Header) bool
  • func (g GenericHook) Handle(w http.ResponseWriter, r *http.Request, repo *Repo) (int, error)
• type Git
  • func (g Git) Repo(i int) *Repo
• type GithubHook
  • func (g GithubHook) DoesHandle(h http.Header) bool
  • func (g GithubHook) Handle(w http.ResponseWriter, r *http.Request, repo *Repo) (int, error)
• type GitlabHook
  • func (g GitlabHook) DoesHandle(h http.Header) bool
  • func (g GitlabHook) Handle(w http.ResponseWriter, r *http.Request, repo *Repo) (int, error)
• type Repo
  • func (r *Repo) Prepare() error
  • func (r *Repo) Pull() error
• type Then
  • func NewLongThen(command string, args ...string) Then
  • func NewThen(command string, args ...string) Then
• type WebHook
  • func (h WebHook) ServeHTTP(w http.ResponseWriter, r *http.Request) (int, error)

Constants

const (
	// DefaultInterval is the minimum interval to delay before
	// requesting another git pull
	DefaultInterval time.Duration = time.Hour * 1
)

Variables

var (
	// Services holds all git pulling services and provides the function to
	// stop them.
	Services = &services{}
)

Functions

func Init

func Init() error

Init validates git installation, locates the git executable binary in PATH and check for available shell to use.

func Logger

func Logger() *log.Logger

Logger gets the currently available logger

func SetLogger

func SetLogger(l *log.Logger)

SetLogger sets the current logger to l

func SetOS

func SetOS(os gitos.OS)

SetOS sets the OS to be used. Intended to be used for tests to abstract OS level git actions.

func Setup

func Setup(c *setup.Controller) (middleware.Middleware, error)

Git configures a new Git service routine.

func Start

func Start(repo *Repo)

Start starts a new background service to pull periodically.

Types

type BitbucketHook

type BitbucketHook struct{}

func (BitbucketHook) DoesHandle

func (b BitbucketHook) DoesHandle(h http.Header) bool

func (BitbucketHook) Handle

func (b BitbucketHook) Handle(w http.ResponseWriter, r *http.Request, repo *Repo) (int, error)

type GenericHook

type GenericHook struct{}

func (GenericHook) DoesHandle

func (g GenericHook) DoesHandle(h http.Header) bool

func (GenericHook) Handle

func (g GenericHook) Handle(w http.ResponseWriter, r *http.Request, repo *Repo) (int, error)

type Git

type Git []*Repo

Git represent multiple repositories.

func (Git) Repo

func (g Git) Repo(i int) *Repo

Repo retrieves repository at i or nil if not found.

type GithubHook

type GithubHook struct{}

func (GithubHook) DoesHandle

func (g GithubHook) DoesHandle(h http.Header) bool

func (GithubHook) Handle

func (g GithubHook) Handle(w http.ResponseWriter, r *http.Request, repo *Repo) (int, error)

type GitlabHook

type GitlabHook struct{}

func (GitlabHook) DoesHandle

func (g GitlabHook) DoesHandle(h http.Header) bool

func (GitlabHook) Handle

func (g GitlabHook) Handle(w http.ResponseWriter, r *http.Request, repo *Repo) (int, error)

type Repo

type Repo struct {
	URL      string        // Repository URL
	Path     string        // Directory to pull to
	Host     string        // Git domain host e.g. github.com
	Branch   string        // Git branch
	KeyPath  string        // Path to private ssh key
	Interval time.Duration // Interval between pulls
	Then     []Then        // Commands to execute after successful git pull

	sync.Mutex

	HookUrl    string // url to listen on for webhooks
	HookSecret string // secret to validate hooks
	// contains filtered or unexported fields
}

Repo is the structure that holds required information of a git repository.

func (*Repo) Prepare

func (r *Repo) Prepare() error

Prepare prepares for a git pull and validates the configured directory

func (*Repo) Pull

func (r *Repo) Pull() error

Pull attempts a git pull. It retries at most numRetries times if error occurs

type Then

type Then interface {
	Command() string
	Exec(string) error
}

Then is the command executed after successful pull.

func NewLongThen

func NewLongThen(command string, args ...string) Then

NewLongThen creates a new long running Then comand.

func NewThen

func NewThen(command string, args ...string) Then

NewThen creates a new Then command.

type WebHook

type WebHook struct {
	Repos []*Repo
	Next  middleware.Handler
}

Middleware for handling web hooks of git providers

func (WebHook) ServeHTTP

func (h WebHook) ServeHTTP(w http.ResponseWriter, r *http.Request) (int, error)

ServeHTTP implements the middlware.Handler interface.