caddy_webhook

README

caddy-webhook

Caddy v2 module for serving a webhook.

English | 中文

Installation

Build with xcaddy

xcaddy build \
  --with github.com/WingLim/caddy-webhook

Run in Docker

See caddy-docker for Dockerfile.

DockerHub: winglim/caddy

GitHub Package: winglim/caddy

Usage

Now supported webhook type:

• github
• gitlab
• gitee
• bitbucket
• gogs

Caddyfile Format

Notice: webhook block should be the last handler of route. After receive request and handle it, we return nil instead of the next middleware. So, the rest handler after webhook will not work.

webhook [<repo> <path>] {
    repo       <text>
    path       <text>
    branch     <text>
    depth      <int>
    type       <text>
    secret     <text>
    command    <text>...
    key	       <text>
    username   <text>
    password   <text>
    token      <text>
    submodule
}

• repo - git repository url, supported http, https and ssh.
• path - path to clone and update repository.
• branch - branch to pull. Default is main.
• depth - depth for pull. Default is 0.
• type - webhook type. Default is github.
• secret - secret to verify webhook request.
• submodule - enable recurse submodules.
• command - the command run when repo initializes or get the correct webhook request.
• key - path of private key, using to access git with ssh.
• username - username for http auth.
• password - password for http auth.
• token - GitHub personal access token.

Example

The full example to run a hugo blog:

Caddyfile:

example.com

root www
file_server

route /webhook {
    webhook {
        repo https://github.com/WingLim/winglim.github.io.git
        path blog
        branch hugo
        command hugo --destination ../www
        submodule   
    }
}

With the config above, webhook module will do things:

1. Clone https://github.com/WingLim/winglim.github.io.git to blog when initializes.

   1. If the repo is already exist, will fetch and checkout to the branch you set.

2. Run the command hugo --destination ../www inside the blog directory.

3. Listen and serve at /webhook and handle the webhook request.

   1. When receive correct webhook request, will update repo and do step 2 again.

Thanks to

• caddygit - Git module for Caddy v2
• caddy-git - git middleware for Caddy
• caddy-exec - Caddy v2 module for running one-off commands

Documentation

Index

• Constants
• func ValidateRequest(r *http.Request) error
• type Cmd
  • func (c *Cmd) AddCommand(command []string, path string)
  • func (c *Cmd) Run(logger *zap.Logger)
• type Repo
  • func NewRepo(w *WebHook) *Repo
  • func (r *Repo) Setup(ctx context.Context) error
  • func (r *Repo) Update(ctx context.Context) error
• type WebHook
  • func (*WebHook) CaddyModule() caddy.ModuleInfo
  • func (w *WebHook) Provision(ctx caddy.Context) error
  • func (w *WebHook) ServeHTTP(rw http.ResponseWriter, r *http.Request, next caddyhttp.Handler) error
  • func (w *WebHook) UnmarshlCaddyfile(d *caddyfile.Dispenser) error
  • func (w *WebHook) Validate() error

Constants

const (
	DefaultRemote = "origin"
	DefaultBranch = "main"
)

Functions

func ValidateRequest

func ValidateRequest(r *http.Request) error

ValidateRequest validates webhook request, the webhook request should be POST.

Types

type Cmd

type Cmd struct {
	Command string
	Args    []string
	Path    string
}

func (*Cmd) AddCommand

func (c *Cmd) AddCommand(command []string, path string)

func (*Cmd) Run

func (c *Cmd) Run(logger *zap.Logger)

type Repo

type Repo struct {
	URL       string
	Path      string
	Branch    string
	Depth     int
	Secret    string
	Submodule git.SubmoduleRescursivity
	Auth      transport.AuthMethod
	// contains filtered or unexported fields
}

Repo tells information about the git repository.

func NewRepo

func NewRepo(w *WebHook) *Repo

NewRepo creates a new repo with options.

func (*Repo) Setup

func (r *Repo) Setup(ctx context.Context) error

Setup initializes the git repository by either cloning or opening it.

func (*Repo) Update

func (r *Repo) Update(ctx context.Context) error

Update pulls updates from the remote repository into current worktree.

type WebHook

type WebHook struct {
	// Git repository URL, supported http, https and ssh.
	Repository string `json:"repo,omitempty"`

	// Path to clone and update repository.
	Path string `json:"path,omitempty"`

	// Branch to pull.
	// Default to `main`.
	Branch string `json:"branch,omitempty"`

	// Webhook type.
	// Default to `github`.
	Type string `json:"type,omitempty"`

	// Secret to verify webhook request.
	Secret string `json:"secret,omitempty"`

	// Depth for pull and fetch.
	// Default to `0`.
	Depth string `json:"depth,omitempty"`

	// Enable recurse submodules.
	Submodule bool `json:"submodule,omitempty"`

	// Command to run when repo initializes or receive a
	// correct webhook request.
	Command []string `json:"command,omitempty"`

	// Path of private key, using to access git with ssh.
	Key string `json:"key,omitempty"`

	// Password of private key.
	KeyPassword string `json:"key_password,omitempty"`

	// Username for http auth.
	Username string `json:"username,omitempty"`

	// Password for http auth.
	Password string `json:"password,omitempty"`

	// GitHub personal access token.
	Token string `json:"token,omitempty"`
	// contains filtered or unexported fields
}

WebHook is the module configuration.

func (*WebHook) CaddyModule

func (*WebHook) CaddyModule() caddy.ModuleInfo

CaddyModule returns the Caddy module information.

func (*WebHook) Provision

func (w *WebHook) Provision(ctx caddy.Context) error

Provision set's up webhook configuration.

func (*WebHook) ServeHTTP

func (w *WebHook) ServeHTTP(rw http.ResponseWriter, r *http.Request, next caddyhttp.Handler) error

ServeHTTP implements caddyhttp.MiddlewareHandler.

func (*WebHook) UnmarshlCaddyfile

func (w *WebHook) UnmarshlCaddyfile(d *caddyfile.Dispenser) error

UnmarshCaddyfile configures the handler directive from Caddyfile. Syntax:

webhook [<url> <path>] {
	repo		<text>
	path 		<text>
	branch 		<text>
	depth		<int>
	type 		<text>
	secret		<text>
	command		<text>...
	key			<text>
	username	<text>
	password	<text>
	token		<text>
	submodule
}

func (*WebHook) Validate

func (w *WebHook) Validate() error

Validate ensures webhook's configuration is valid.