Restrucutred and extended documentation
This commit is contained in:
parent
a555f47f46
commit
76dc2203f5
89
DOCS.md
89
DOCS.md
|
@ -1,13 +1,14 @@
|
||||||
Use the Webhook plugin to notify services via Webhook when a build completes.
|
Use the Webhook plugin to notify services via Webhook when a build completes.
|
||||||
You will need to supply Drone with outgoing Webhook URLs.
|
You will need to supply Drone with outgoing Webhook URLs. You can override the
|
||||||
|
default configuration with the following parameters:
|
||||||
|
|
||||||
The following parameters are used to configure outgoing Webhooks:
|
* `urls` - JSON payloads are sent to each URL
|
||||||
|
|
||||||
* `urls` - JSON payloads are sent to each URL listed here
|
|
||||||
* `method` - HTTP request method. Defaults to `POST`
|
* `method` - HTTP request method. Defaults to `POST`
|
||||||
* `header` - HTTP request header map
|
* `header` - HTTP request header map
|
||||||
|
|
||||||
The following is a sample Webhook configuration in your .drone.yml file:
|
## Example
|
||||||
|
|
||||||
|
The following is a sample configuration in your .drone.yml file:
|
||||||
|
|
||||||
```yaml
|
```yaml
|
||||||
notify:
|
notify:
|
||||||
|
@ -19,53 +20,10 @@ notify:
|
||||||
Authorization: pa55word
|
Authorization: pa55word
|
||||||
```
|
```
|
||||||
|
|
||||||
The following is an example Webhook payload (whitespace added):
|
### Custom Body
|
||||||
|
|
||||||
```json
|
In some cases you may want to submit a custom payload in the body of your hook.
|
||||||
{
|
For the use case we expose the following additional parameters:
|
||||||
"build": {
|
|
||||||
"author": "johnsmith",
|
|
||||||
"author_avatar": "",
|
|
||||||
"author_email": "john.smith@gmail.com",
|
|
||||||
"branch": "master",
|
|
||||||
"commit": "9f2849d5",
|
|
||||||
"created_at": 0,
|
|
||||||
"enqueued_at": 0,
|
|
||||||
"event": "",
|
|
||||||
"finished_at": 1421029813,
|
|
||||||
"link_url": "",
|
|
||||||
"message": "Update the Readme",
|
|
||||||
"number": 22,
|
|
||||||
"ref": "",
|
|
||||||
"refspec": "",
|
|
||||||
"remote": "",
|
|
||||||
"started_at": 1421029603,
|
|
||||||
"status": "success",
|
|
||||||
"timestamp": 0,
|
|
||||||
"title": ""
|
|
||||||
},
|
|
||||||
"repo": {
|
|
||||||
"allow_deploys": false,
|
|
||||||
"allow_pr": false,
|
|
||||||
"allow_push": false,
|
|
||||||
"allow_tags": false,
|
|
||||||
"avatar_url": "",
|
|
||||||
"clone_url": "",
|
|
||||||
"default_branch": "",
|
|
||||||
"full_name": "foo/bar",
|
|
||||||
"link_url": "",
|
|
||||||
"name": "bar",
|
|
||||||
"owner": "foo",
|
|
||||||
"private": false,
|
|
||||||
"timeout": 0,
|
|
||||||
"trusted": false
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
## Custom Body
|
|
||||||
|
|
||||||
In some cases you may want to submit a custom payload in the body of your hook. For the use case we expose the following additional parameters:
|
|
||||||
|
|
||||||
* `template` - Handlebars template to create a custom payload body. See [docs](http://handlebarsjs.com/)
|
* `template` - Handlebars template to create a custom payload body. See [docs](http://handlebarsjs.com/)
|
||||||
* `content_type` - HTTP request content type
|
* `content_type` - HTTP request content type
|
||||||
|
@ -85,15 +43,18 @@ notify:
|
||||||
commit: {{build.commit}}
|
commit: {{build.commit}}
|
||||||
```
|
```
|
||||||
|
|
||||||
## Basic Authentication
|
### Basic Authentication
|
||||||
|
|
||||||
>It is important to note that with HTTP Basic Authentication the provided username and password are not encrypted.
|
> It is important to note that with HTTP Basic Authentication the provided
|
||||||
|
> username and password are not encrypted.
|
||||||
|
|
||||||
In some cases your webhook may need to authenticate with another service. You can set the basic `Authentication` header with a username and password. For these use cases we expose the following additional parameters:
|
In some cases your webhook may need to authenticate with another service. You
|
||||||
|
can set the basic `Authentication` header with a username and password. For
|
||||||
|
these use cases we expose the following additional parameters:
|
||||||
|
|
||||||
* `auth` - Sets the request's `Authorization` header to use HTTP Basic Authentication with the provided username and password below.
|
* `auth` - Sets the request's `Authorization` header to use HTTP Basic Authentication with the provided username and password below
|
||||||
* `username` - The username as a string.
|
* `username` - The username as a string
|
||||||
* `password` - The password as a string.
|
* `password` - The password as a string
|
||||||
|
|
||||||
Example configuration to include HTTP Basic Authentication:
|
Example configuration to include HTTP Basic Authentication:
|
||||||
|
|
||||||
|
@ -108,13 +69,17 @@ notify:
|
||||||
- https://tower.example.com/...
|
- https://tower.example.com/...
|
||||||
```
|
```
|
||||||
|
|
||||||
## Debugging Webhooks
|
### Debugging Webhooks
|
||||||
|
|
||||||
>If you have private variables that are encrypted and hidden in `.drone.sec`, remember that the `debug` flag may print out those sensitive values. Please use `dubug: true` wisely.
|
> If you have private variables that are encrypted and hidden in `.drone.sec`,
|
||||||
|
> remember that the `debug` flag may print out those sensitive values. Please
|
||||||
|
> use `debug: true` wisely.
|
||||||
|
|
||||||
In some cases complicated webhooks may need debugging to ensure `urls`, `template`, `auth` and more a properly configured. For these use cases we expose the following `debug` parameter:
|
In some cases complicated webhooks may need debugging to ensure `urls`,
|
||||||
|
`template`, `auth` and more a properly configured. For these use cases we expose
|
||||||
|
the following `debug` parameter:
|
||||||
|
|
||||||
* `debug` - If `debug: true` it will print out each URL request and response information.
|
* `debug` - If `true` it will print out each URL request and response information
|
||||||
|
|
||||||
Example configuration to include the `debug` parameter:
|
Example configuration to include the `debug` parameter:
|
||||||
|
|
||||||
|
@ -135,7 +100,7 @@ notify:
|
||||||
|
|
||||||
Example of a debug print result:
|
Example of a debug print result:
|
||||||
|
|
||||||
```yaml
|
```
|
||||||
[debug] Webhook 1
|
[debug] Webhook 1
|
||||||
URL: http://tower.example.com/api/v1/job_templates/44/launch/
|
URL: http://tower.example.com/api/v1/job_templates/44/launch/
|
||||||
METHOD: POST
|
METHOD: POST
|
||||||
|
|
18
README.md
18
README.md
|
@ -1,12 +1,11 @@
|
||||||
# drone-webhook
|
# drone-webhook
|
||||||
Drone plugin for sending Webhook notifications.
|
|
||||||
|
|
||||||
## Overview
|
Drone plugin for sending notifications via Webhook
|
||||||
|
|
||||||
This plugin is responsible for sending build notifications via Webhooks:
|
## Usage
|
||||||
|
|
||||||
```sh
|
```
|
||||||
./drone-webhooks <<EOF
|
./drone-webhook <<EOF
|
||||||
{
|
{
|
||||||
"repo" : {
|
"repo" : {
|
||||||
"owner": "foo",
|
"owner": "foo",
|
||||||
|
@ -44,15 +43,14 @@ EOF
|
||||||
|
|
||||||
## Docker
|
## Docker
|
||||||
|
|
||||||
Build the Docker container. Note that we need to use the `-netgo` tag so that
|
Build the Docker container using `make`:
|
||||||
the binary is built without a CGO dependency:
|
|
||||||
|
|
||||||
```sh
|
```
|
||||||
CGO_ENABLED=0 go build -a -tags netgo
|
make deps build
|
||||||
docker build --rm=true -t plugins/drone-webhook .
|
docker build --rm=true -t plugins/drone-webhook .
|
||||||
```
|
```
|
||||||
|
|
||||||
Send a Webhook notification:
|
### Example
|
||||||
|
|
||||||
```sh
|
```sh
|
||||||
docker run -i plugins/drone-webhook <<EOF
|
docker run -i plugins/drone-webhook <<EOF
|
||||||
|
|
Loading…
Reference in New Issue