{"id":13543202,"url":"https://github.com/abiosoft/caddy-git","last_synced_at":"2025-05-16T06:07:59.038Z","repository":{"id":34287246,"uuid":"38176264","full_name":"abiosoft/caddy-git","owner":"abiosoft","description":"git middleware for Caddy","archived":false,"fork":false,"pushed_at":"2019-12-04T07:30:08.000Z","size":129,"stargazers_count":204,"open_issues_count":29,"forks_count":43,"subscribers_count":12,"default_branch":"master","last_synced_at":"2024-11-24T17:09:54.489Z","etag":null,"topics":["caddy","caddy-plugin","git","go","webhook"],"latest_commit_sha":null,"homepage":"http://caddyserver.com/docs/http.git","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":"EPCCed/wee_archie","license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/abiosoft.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-06-27T21:38:41.000Z","updated_at":"2024-10-27T14:16:20.000Z","dependencies_parsed_at":"2022-08-26T12:23:56.748Z","dependency_job_id":null,"html_url":"https://github.com/abiosoft/caddy-git","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/abiosoft%2Fcaddy-git","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/abiosoft%2Fcaddy-git/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/abiosoft%2Fcaddy-git/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/abiosoft%2Fcaddy-git/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/abiosoft","download_url":"https://codeload.github.com/abiosoft/caddy-git/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254478193,"owners_count":22077676,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["caddy","caddy-plugin","git","go","webhook"],"created_at":"2024-08-01T11:00:25.842Z","updated_at":"2025-05-16T06:07:56.593Z","avatar_url":"https://github.com/abiosoft.png","language":"Go","readme":"# git\n\nMiddleware for [Caddy](https://caddyserver.com).\n\n[![Build Status](https://travis-ci.org/abiosoft/caddy-git.svg?branch=master)](https://travis-ci.org/abiosoft/caddy-git)\n\ngit clones a git repository into the site. This makes it possible to deploy your site with a simple git push.\n\nThe 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.\n\nIf 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.\n\n**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.)\n\n## Syntax\n\n```\ngit repo [path]\n```\n* **repo** is the URL to the repository; SSH and HTTPS URLs are supported\n* **path** is the path, relative to site root, to clone the repository into; default is site root\n\nThis simplified syntax pulls from master every 3600 seconds (1 hour) and only works for public repositories.\n\nFor more control or to use a private repository, use the following syntax:\n\n```\ngit [repo path] {\n\trepo        repo\n\tpath        path\n\tbranch      branch\n\tkey         key\n\tinterval    interval\n\tclone_args  args\n\tpull_args   args\n\thook        path secret\n\thook_type   type\n\tthen        command [args...]\n\tthen_long   command [args...]\n}\n```\n* **repo** is the URL to the repository; SSH and HTTPS URLs are supported.\n* **path** is the path to clone the repository into; default is site root. It can be absolute or relative (to site root).\n* **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.\n* **key** is the path to the SSH private key; only required for private repositories.\n* **interval** is the number of seconds between pulls; default is 3600 (1 hour), minimum 5. An interval of -1 disables periodic pull.\n* **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.\n* **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.\n* **path** and **secret** are used to create a webhook which pulls the latest right after a push. This is limited to the [supported webhooks](#supported-webhooks). **secret** is currently supported for GitHub, Gitlab and Travis hooks only.\n* **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](#supported-webhooks). This is a requirement for generic webhook.\n* **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.\n\nEach 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.\n\n### Webhooks\n\nA 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](https://docs.travis-ci.com/user/notifications/#Configuring-webhook-notifications) in your `.travis.yml`. Make sure your webhooks are set to deliver JSON data!\n\nThe JSON payload should include [at least a `ref` key](#user-content-generic-format), but all the default supported webhooks will handle this for you.\n\nThe 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](https://git-scm.com/docs/githooks#_post_merge) script or another git hook to rebuild any needed files (updating [SASS](http://sass-lang.com/) styles and regenerating [Hugo](https://gohugo.io/) sites are common use-cases), although the [`then`](#user-content-then-example) parameter can also be used for simpler cases.\n\nNote 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.\n\n#### Supported Webhooks\n\n* [github](https://github.com)\n* [gitlab](https://gitlab.com)\n* [bitbucket](https://bitbucket.org)\n* [travis](https://travis-ci.org)\n* [gogs](https://gogs.io)\n* [gitee](https://gitee.com)\n* generic\n\n## Examples\n\nPublic repository pulled into site root every hour:\n```\ngit github.com/user/myproject\n```\n\nPublic repository pulled into the \"subfolder\" directory in the site root:\n```\ngit github.com/user/myproject subfolder\n```\n\nPrivate repository pulled into the \"subfolder\" directory with tag v1.0 once per day:\n```\ngit {\n\trepo     git@github.com:user/myproject\n\tbranch   v1.0\n\tkey      /home/user/.ssh/id_rsa\n\tpath     subfolder\n\tinterval 86400\n}\n```\n\n\u003ca name=\"then-example\"\u003e\u003c/a\u003e\nGenerate a static site with [Hugo](http://gohugo.io) after each pull:\n```\ngit github.com/user/site {\n\tpath  ../\n\tthen  hugo --destination=/home/user/hugosite/public\n}\n```\n\nPart of a Caddyfile for a PHP site that gets changes from a private repo:\n```\ngit git@github.com:user/myphpsite {\n\tkey /home/user/.ssh/id_rsa\n}\nfastcgi / 127.0.0.1:9000 php\n```\n\nSpecifying a webhook:\n```\ngit git@github.com:user/site {\n\thook /webhook secret-password\n}\n```\n\nYou might need quotes `\"secret-password\"` around your secret if it contains any special characters, or you get an error.\n\n\u003ca name=\"generic_format\"\u003e\u003c/a\u003e\nGeneric webhook payload: `\u003cbranch\u003e` is branch name e.g. `master`.\n```\n{\n\t\"ref\" : \"refs/heads/\u003cbranch\u003e\"\n}\n```\n\n","funding_links":[],"categories":["Go"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fabiosoft%2Fcaddy-git","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fabiosoft%2Fcaddy-git","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fabiosoft%2Fcaddy-git/lists"}