git

package module
v0.0.0-...-fbc8e02 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 19, 2019 License: MIT Imports: 23 Imported by: 0

README

git

Middleware for Caddy.

Build Status

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 [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
	clone_args  args
	pull_args   args
	hook        path secret
	hook_type   type
	then        command [args...]
	then_long   command [args...]
}
  • 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.
  • 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. An interval of -1 disables periodic pull.
  • clone_args is the additional cli args to pass to git clone e.g. --depth=1. git clone is called when the source is being fetched the first time.
  • pull_args is the additional cli args to pass to git pull e.g. -s recursive -X theirs. git pull is used when the source is being updated.
  • 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:

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
}

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>"
}

Documentation

Index

Constants

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

Variables

View Source 
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 Start 

func Start(repo *Repo)

Start starts a new background service to pull periodically.

Types

type BitbucketHook 

type BitbucketHook struct{}

BitbucketHook is webhook for BitBucket.org.

func (BitbucketHook) DoesHandle 

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

DoesHandle satisfies hookHandler.

func (BitbucketHook) Handle 

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

Handle satisfies hookHandler.

type GenericHook 

type GenericHook struct{}

GenericHook is generic webhook.

func (GenericHook) DoesHandle 

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

DoesHandle satisfies hookHandler.

func (GenericHook) Handle 

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

Handle satisfies hookhandler.

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 GiteeHook 

type GiteeHook struct{}

GiteeHook is webhook for gitee.com

func (GiteeHook) DoesHandle 

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

DoesHandle satisfies hookHandler.

func (GiteeHook) Handle 

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

Handle satisfies hookHandler.

type GithubHook 

type GithubHook struct{}

GithubHook is webhook for Github.com.

func (GithubHook) DoesHandle 

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

DoesHandle satisfies hookHandler.

func (GithubHook) Handle 

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

Handle satisfies hookHandler.

type GitlabHook 

type GitlabHook struct{}

GitlabHook is webhook for gitlab.com

func (GitlabHook) DoesHandle 

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

DoesHandle satisfies hookHandler.

func (GitlabHook) Handle 

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

Handle satisfies hookHandler.

type GogsHook 

type GogsHook struct{}

GogsHook is the webhook for gogs.io.

func (GogsHook) DoesHandle 

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

DoesHandle satisfies hookHandler.

func (GogsHook) Handle 

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

Handle satisfies hookHandler.

type HookConfig 

type HookConfig struct {
	URL    string // url to listen on for webhooks
	Secret string // secret to validate hooks
	Type   string // type of Webhook
}

HookConfig is a webhook handler configuration.

type Repo 

type Repo struct {
	URL       RepoURL       // 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
	CloneArgs []string      // Additonal cli args to pass to git clone
	PullArgs  []string      // Additonal cli args to pass to git pull
	Then      []Then        // Commands to execute after successful git pull

	Hook HookConfig // Webhook configuration
	sync.Mutex
	// 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 RepoURL 

type RepoURL string

RepoURL is the repository url.

func (RepoURL) String 

func (r RepoURL) String() string

String satisfies stringer and attempts to strip off authentication info from url if it exists.

func (RepoURL) Val 

func (r RepoURL) Val() string

Val returns git friendly Val that can be passed to git clone.

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 TravisHook 

type TravisHook struct{}

TravisHook is webhook for travis-ci.org

func (TravisHook) DoesHandle 

func (t TravisHook) DoesHandle(h http.Header) bool

DoesHandle satisfies hookHandler.

func (TravisHook) Handle 

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

Handle satisfies hookHandler.

type WebHook 

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

WebHook is 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.

Source Files

View all Source files

Directories

Path Synopsis
Package gittest is a test package for the git middleware.
 Package gittest is a test package for the git middleware.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.