Finish github webhooks integration

2 files changed, 105 insertions, 0 deletions

diff --git a/docs/automatic-actions.markdown b/docs/automatic-actions.markdown
index 631919ea..cf350a2f 100644
--- a/docs/automatic-actions.markdown
+++ b/docs/automatic-actions.markdown
@@ -32,6 +32,13 @@ List of available events
 - Closing a task
 - Task creation or modification
 - Task assignee change
+- Github commit received
+- Github issue opened
+- Github issue closed
+- Github issue reopened
+- Github issue assignee change
+- Github issue label change
+- Github issue comment created
 
 List of available actions
 -------------------------
@@ -44,6 +51,10 @@ List of available actions
 - Assign a color to a specific user
 - Assign automatically a color based on a category
 - Assign automatically a category based on a color
+- Create a task from an external provider
+- Change the assignee based on an external username
+- Change the category based on an external label
+- Create a comment from an external provider
 
 Examples
 --------
diff --git a/docs/github-webhooks.markdown b/docs/github-webhooks.markdown
new file mode 100644
index 00000000..cdbb69c9
--- /dev/null
+++ b/docs/github-webhooks.markdown
@@ -0,0 +1,94 @@
+Github webhook integration
+==========================
+
+Kanboard can be synchronized with Github.
+Currently, it's only a one-way synchronization: Github to Kanboard.
+
+Github webhooks are plugged to Kanboard automatic actions.
+When an event occurs on Github, an action can be performed on Kanboard.
+
+List of available events
+------------------------
+
+- Github commit received
+- Github issue opened
+- Github issue closed
+- Github issue reopened
+- Github issue assignee change
+- Github issue label change
+- Github issue comment created
+
+List of available actions
+-------------------------
+
+- Create a task from an external provider
+- Change the assignee based on an external username
+- Change the category based on an external label
+- Create a comment from an external provider
+
+Configuration on Github
+-----------------------
+
+Go to your project settings page, on the left choose "Webhooks & Services", then click on the button "Add webhook".
+
+![Github configuration](http://kanboard.net/screenshots/documentation/github-webhooks.png)
+
+- **Payload url**: This url is available on Kanboard, go to "projects", select your project, at the bottom of the page, you have a section Github webhooks, just copy and paste the link.
+- Select **"Send me everything"**
+
+Each time an event happens, Github will send an event to Kanboard now.
+The Kanboard webhook url is protected by a random token.
+
+Everything else is handled by automatic actions in your Kanboard project settings.
+
+Examples
+--------
+
+### Close a Kanboard task when a commit pushed to Github
+
+- Choose the event: **Github commit received**
+- Choose the action: **Close the task**
+
+When one or more commits are sent to Github, Kanboard will receive the information, each commit message with a task number included will be closed.
+
+Example:
+
+- Commit message: "Fix bug #1234"
+- That will close the Kanboard task #1234
+
+### Create a Kanboard task when a new issue is opened on Github
+
+- Choose the event: **Github issue opened**
+- Choose the action: **Create a task from an external provider**
+
+When a task is created from a Github issue, the link to the issue is added to the description and the task have a new field named "Reference" (this is the Github ticket number).
+
+### Close a Kanboard task when an issue is closed on Github
+
+- Choose the event: **Github issue closed**
+- Choose the action: **Close the task**
+
+### Reopen a Kanboard task when an issue is reopened on Github
+
+- Choose the event: **Github issue reopened**
+- Choose the action: **Open the task**
+
+### Assign a task to a Kanboard user when an issue is assigned on Github
+
+- Choose the event: **Github issue assignee change**
+- Choose the action: **Change the assignee based on an external username**
+
+Note: The username must be the same between Github and Kanboard.
+
+### Assign a category when an issue is tagged on Github
+
+- Choose the event: **Github issue label change**
+- Choose the action: **Change the category based on an external label**
+- Define the label and the category
+
+### Create a comment on Kanboard when an issue is commented on Github
+
+- Choose the event: **Github issue comment created**
+- Choose the action: **Create a comment from an external provider**
+
+Note: The username of the comment author must be the same between Github and Kanboard and the task must exists before.