You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@devlake.apache.org by yu...@apache.org on 2022/09/21 12:38:28 UTC
[incubator-devlake-website] branch main updated (bc50ea08d -> d6decf782)
This is an automated email from the ASF dual-hosted git repository.
yumeng pushed a change to branch main
in repository https://gitbox.apache.org/repos/asf/incubator-devlake-website.git
from bc50ea08d docs: add a contributor zhangqi
new b7abe6090 doc: add the doc of the plugin webbhook
new 58442bb00 Update webhook.md
new c74c53512 fix: replace a text
new 482cddc53 add webhook doc on ConfigUI
new e66df0052 Update webhook.md
new d6decf782 Update webhook.md
The 6 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails. The revisions
listed as "add" were already present in the repository and have only
been added to this reference.
Summary of changes:
docs/Plugins/webhook.md | 173 +++++++++++++++++++++++++++++++++++
docs/UserManuals/ConfigUI/webhook.md | 20 ++++
2 files changed, 193 insertions(+)
create mode 100644 docs/Plugins/webhook.md
create mode 100644 docs/UserManuals/ConfigUI/webhook.md
[incubator-devlake-website] 06/06: Update webhook.md
Posted by yu...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
yumeng pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/incubator-devlake-website.git
commit d6decf78283b894311f83b7933a46d8aa558062b
Author: Yumeng Wang <yu...@merico.dev>
AuthorDate: Wed Sep 21 20:30:37 2022 +0800
Update webhook.md
---
docs/UserManuals/ConfigUI/webhook.md | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/docs/UserManuals/ConfigUI/webhook.md b/docs/UserManuals/ConfigUI/webhook.md
index ed50df37c..a879e3117 100644
--- a/docs/UserManuals/ConfigUI/webhook.md
+++ b/docs/UserManuals/ConfigUI/webhook.md
@@ -13,8 +13,8 @@ Name your connection.
We recommand that you give your webhook connection a unique name so that you can identify and manage where you have used it later.
### Use Webhook
-After cicking on "Generate POST URL", you will find four webhook URLs. Copy the ones that suits your usage into your CI or issue tracking systems. You can always come back to the webhook page to copy the URLS later on.
+After cicking on "Generate POST URL", you will find four webhook URLs. Copy the ones that suits your usage into your CI or issue tracking systems. You can always come back to the webhook page to copy the URLs later on.
-For more usage: [plugins/webhook](/Plugins/webhook.md).
\ No newline at end of file
+For more usage: [plugins/webhook](/Plugins/webhook.md).
[incubator-devlake-website] 01/06: doc: add the doc of the plugin webbhook
Posted by yu...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
yumeng pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/incubator-devlake-website.git
commit b7abe60905b8701dfa72ead7c611433ca850ef27
Author: linyh <ya...@meri.co>
AuthorDate: Wed Sep 21 01:26:45 2022 +0800
doc: add the doc of the plugin webbhook
---
docs/Plugins/webhook.md | 173 ++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 173 insertions(+)
diff --git a/docs/Plugins/webhook.md b/docs/Plugins/webhook.md
new file mode 100644
index 000000000..7acdee38d
--- /dev/null
+++ b/docs/Plugins/webhook.md
@@ -0,0 +1,173 @@
+---
+title: "Webhook"
+description: >
+ Webhook Plugin
+---
+
+## Summary
+
+[Webhooks](https://en.wikipedia.org/wiki/Webhook) are HTTPs that you need to request. They should be triggered in your deploy and bug recorder systems, such as build shells in Jenkins or Jira.
+
+
+(picture from the Internet)
+
+Here, your systems play the roles of system A as the picture, and Apache DevLake is system B. Now, you can use webhooks to:
+
+* record bugs or incidents when DevLake cannot collect data from issue applications directly.
+* detect code deployments by custom deploy-time measurement
+
+DevLake does not limit the number of webhook requests. **But Notice**: Your Database or other servers may not handle unlimited requests.
+
+## Configuration
+Configuring Webhook via config-ui.
+
+First, You can create a webhook connection.
+
+
+We suggest that one connection must be used in one system. So you can input the name of your system here.
+
+Then, you can find the webhook URLs here. Copy what you need. (Or copy when you need them)
+
+
+
+
+
+## Incident / Issue
+
+If you want to collect issue or incident data from your system, you can use the webhook of issues.
+
+There are 2 hooks. **Notice**: `https://sample-url.com/` and `1` should be replaced with your URL and connectionId.
+
+#### Update or Create issues
+
+`POST https://sample-url.com/api/plugins/webhook/1/issues`
+
+Need to be called when an issue or incident is created. The body includes columns as follows:
+
+```
+board_key: issue belongs to which board/project
+url(Optional): issue's URL
+issue_key: issue's key, needs to be unique in a connection
+title
+description(Optional)
+epic_key(Optional): in which epic.
+type(Optional): type, such as bug/incident/epic/...
+status: issue's status. Must be one of TODO DONE IN_PROGRESS
+original_status: status in your system, such as created/open/closed/...
+story_point(Optional)
+resolution_date(Optional): date, Format should be 2020-01-01T12:00:00+00:00
+created_date: date, Format should be 2020-01-01T12:00:00+00:00
+updated_date(Optional): date, Format should be 2020-01-01T12:00:00+00:00
+lead_time_minutes(Optional): how long from this issue accepted to develop
+parent_issue_key(Optional)
+priority(Optional)
+original_estimate_minutes(Optional)
+time_spent_minutes(Optional)
+time_remaining_minutes(Optional)
+creator_id(Optional): the user id of the creator
+creator_name(Optional): the user name of the creator, it will just be used to display
+assignee_id(Optional)
+assignee_name(Optional)
+severity(Optional)
+component(Optional): which component is this issue in.
+```
+
+
+
+#### Close issue (Optional)
+
+`POST https://sample-url.com/api/plugins/webhook/1/issue/:boardKey/:issueId/close`
+
+Need to be called when an issue or incident is closed. Replace `:boardKey` and `:issueId` with specific strings and keep the body empty.
+
+
+
+### Sample API Calls
+
+Sample CURL for Issue Creating :
+
+```
+curl http://127.0.0.1:4000/api/plugins/webhook/1/issues -X 'POST' -d '{"board_key":"DLK","url":"","issue_key":"DLK-1234","title":"a feature from DLK","description":"","epic_key":"","type":"BUG","status":"TODO","original_status":"created","story_point":0,"resolution_date":null,"created_date":"2020-01-01T12:00:00+00:00","updated_date":null,"lead_time_minutes":0,"parent_issue_key":"DLK-1200","priority":"","original_estimate_minutes":0,"time_spent_minutes":0,"time_remaining_minutes":0,"creat [...]
+```
+
+Sample CURL for Issue Closing:
+
+```
+curl http://127.0.0.1:4000/api/plugins/webhook/1/issue/DLK/DLK-1234/close -X 'POST'
+```
+
+Read more in Swagger: http://localhost:4000/api/swagger/index.html#/plugins%2Fwebhook/post_plugins_webhook__connectionId_issues.
+
+## Deployment
+
+Adding pipeline webhook in your deploy shells will help you collect data into DevLake.
+
+First, let us know there are 2 entities Tasks and Pipelines. A pipeline means one build or deployment, and a pipeline may have more than one task.
+
+
+
+(Example 1)
+
+For example, we can find 6 tasks like `golangci-lint` and `unit-test` in one GitHub pipeline.
+
+
+
+(Example 2. Picture from the Internet)
+
+In Example 2, we can find 12 Jenkins pipelines.
+
+
+
+(Example 3. Picture from the Internet)
+
+In Example 3, we can find 5 Jenkins pipelines, and these pipelines have 1~4 task(s).
+
+
+
+After figuring out `pipeline` and `task`, we can start to add webhook. 2 hooks need to be added in shells. **Notice**: `https://sample-url.com/` and `1` should be replaced with your URL and connectionId.
+
+#### Update or Create the tasks in the pipeline
+
+This hook should be added when the task starts and finishes. So in Example 3, we need to add 8 CURLs in the 4 tasks.
+
+`POST https://sample-url.com/api/plugins/webhook/1/cicd_tasks`
+
+The body should be a JSON and include columns as follows:
+
+```
+pipeline_name: pipeline's name can be filled by any string unique in a connection
+name: task's name should be unique in one pipeline
+result: Must be one of SUCCESS FAILURE ABORT IN_PROGRESS
+status: Must be one of IN_PROGRESS DONE
+type: one of TEST LINT BUILD DEPLOYMENT
+environment: which type of machine did this task run in. one of PRODUCTION STAGING TESTING
+started_date: date, Format should be 2020-01-01T12:00:00+00:00
+finished_date(Optional): date, Format should be 2020-01-01T12:00:00+00:00
+repo_id: build for which repo/project. It can be a unique string that you can distinguish
+branch(Optional)
+commit_sha(Optional)
+```
+
+
+
+#### Close pipelines
+
+`POST https://sample-url.com/api/plugins/webhook/1/cicd_pipeline/:pipelineName/finish`
+
+This hook should be called to tell DevLake a pipeline finish when a pipeline is completed. `:pipelineName` need to be replaced with the pipeline name in the previous webhook.
+
+### Sample API Calls
+
+Sample CURL for the tasks starting and finishing in deploy pipelines:
+
+```
+curl http://127.0.0.1:4000/api/plugins/webhook/1/cicd_tasks -X 'POST' -d '{"pipeline_name":"A123","name":"unit-test","result":"IN_PROGRESS","status":"IN_PROGRESS","type":"TEST","environment":"PRODUCTION","created_date":"2020-01-01T12:00:00+00:00","finished_date":"2020-01-01T12:59:59+00:00","repo_id":"devlake","branch":"main","commit_sha":"015e3d3b480e417aede5a1293bd61de9b0fd051d"}'
+```
+
+Sample CURL for pipeline completed:
+
+```
+curl http://127.0.0.1:4000/api/plugins/webhook/1/cicd_pipeline/A123/finish -X 'POST' -d ''
+```
+
+Read more in Swagger: http://localhost:4000/api/swagger/index.html#/plugins%2Fwebhook/post_plugins_webhook__connectionId_issues.
[incubator-devlake-website] 05/06: Update webhook.md
Posted by yu...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
yumeng pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/incubator-devlake-website.git
commit e66df00522048a8f03201bbe3199555bd35d5ad3
Author: Yumeng Wang <yu...@merico.dev>
AuthorDate: Wed Sep 21 20:29:54 2022 +0800
Update webhook.md
---
docs/Plugins/webhook.md | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/docs/Plugins/webhook.md b/docs/Plugins/webhook.md
index 779525576..e7ce2153d 100644
--- a/docs/Plugins/webhook.md
+++ b/docs/Plugins/webhook.md
@@ -26,7 +26,7 @@ First, you can create a webhook connection from the Integration page.
We recommand that you give your webhook connection a unique name so that you can identify and manage where you have used it later.
-After cicking on "Generate POST URL", you will find four webhook URLs. Copy the ones that suits your usage into your CI or issue tracking systems. You can always come back to the webhook page to copy the URLS later on.
+After cicking on "Generate POST URL", you will find four webhook URLs. Copy the ones that suits your usage into your CI or issue tracking systems. You can always come back to the webhook page to copy the URLs later on.
[incubator-devlake-website] 03/06: fix: replace a text
Posted by yu...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
yumeng pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/incubator-devlake-website.git
commit c74c53512c800e1f780e44d9b0005fd5df0b17b0
Author: linyh <ya...@meri.co>
AuthorDate: Wed Sep 21 19:51:32 2022 +0800
fix: replace a text
---
docs/Plugins/webhook.md | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/docs/Plugins/webhook.md b/docs/Plugins/webhook.md
index d9bba9e16..779525576 100644
--- a/docs/Plugins/webhook.md
+++ b/docs/Plugins/webhook.md
@@ -36,7 +36,7 @@ After cicking on "Generate POST URL", you will find four webhook URLs. Copy the
If you want to collect issue or incident data from your system, you can use the two webhooks for issues.
-**Notice**: `https://sample-url.com/` and `1` shown in the screenshot above should be replaced with your URL and connectionId.
+**Notice**: The URL shown in the screenshot and the following samples, `https://sample-url.com/...`, is just an example and should be replaced with the actual URL copied from your Config UI.
#### Update or Create Issues
@@ -124,7 +124,7 @@ In Example 3, we can find 5 Jenkins pipelines, and these pipelines have 1~4 task
-After figuring out `pipeline` and `task`, we can start to add webhooks. Two hooks need to be added in shells. **Notice**: `https://sample-url.com/` and `1` should be replaced with your URL and connectionId.
+After figuring out `pipeline` and `task`, we can start to add webhooks. Two hooks need to be added in shells. **Notice**: The URL shown in the following samples, `https://sample-url.com/...`, should be replaced with the actual URL copied from your Config UI.
#### Update or Create Tasks in the Pipeline
[incubator-devlake-website] 04/06: add webhook doc on ConfigUI
Posted by yu...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
yumeng pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/incubator-devlake-website.git
commit 482cddc53159d19adbc4a5e735a7b6c79513d70c
Author: linyh <ya...@meri.co>
AuthorDate: Wed Sep 21 20:18:54 2022 +0800
add webhook doc on ConfigUI
---
docs/UserManuals/ConfigUI/webhook.md | 20 ++++++++++++++++++++
1 file changed, 20 insertions(+)
diff --git a/docs/UserManuals/ConfigUI/webhook.md b/docs/UserManuals/ConfigUI/webhook.md
new file mode 100644
index 000000000..ed50df37c
--- /dev/null
+++ b/docs/UserManuals/ConfigUI/webhook.md
@@ -0,0 +1,20 @@
+---
+title: "Configuring Webhook"
+sidebar_position: 7
+description: Config UI instruction for Webhook
+---
+
+Visit config-ui: `http://localhost:4000`.
+### Add and Update Data Connections
+
+
+#### Connection Name
+Name your connection.
+We recommand that you give your webhook connection a unique name so that you can identify and manage where you have used it later.
+
+### Use Webhook
+After cicking on "Generate POST URL", you will find four webhook URLs. Copy the ones that suits your usage into your CI or issue tracking systems. You can always come back to the webhook page to copy the URLS later on.
+
+
+
+For more usage: [plugins/webhook](/Plugins/webhook.md).
\ No newline at end of file
[incubator-devlake-website] 02/06: Update webhook.md
Posted by yu...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
yumeng pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/incubator-devlake-website.git
commit 58442bb0088efb21be8980f06c30762a7eb1d0aa
Author: Yumeng Wang <yu...@merico.dev>
AuthorDate: Wed Sep 21 19:08:01 2022 +0800
Update webhook.md
---
docs/Plugins/webhook.md | 44 ++++++++++++++++++++++----------------------
1 file changed, 22 insertions(+), 22 deletions(-)
diff --git a/docs/Plugins/webhook.md b/docs/Plugins/webhook.md
index 7acdee38d..d9bba9e16 100644
--- a/docs/Plugins/webhook.md
+++ b/docs/Plugins/webhook.md
@@ -6,27 +6,27 @@ description: >
## Summary
-[Webhooks](https://en.wikipedia.org/wiki/Webhook) are HTTPs that you need to request. They should be triggered in your deploy and bug recorder systems, such as build shells in Jenkins or Jira.
+[Webhooks](https://en.wikipedia.org/wiki/Webhook) are user-defined HTTP callbacks that can be used for causing an event on one site that will trigger certain behavior on another site. They can be triggered in your deployment and bug recording systems, such as build shells in Jenkins or Jira.
-(picture from the Internet)
+(Image from the Internet)
-Here, your systems play the roles of system A as the picture, and Apache DevLake is system B. Now, you can use webhooks to:
+While using webhooks in DevLake, your systems play the roles of system A as shown in the above image, and Apache DevLake as system B. You can use webhooks to:
* record bugs or incidents when DevLake cannot collect data from issue applications directly.
-* detect code deployments by custom deploy-time measurement
+* detect code deployments by using custom deploy-time measurement
-DevLake does not limit the number of webhook requests. **But Notice**: Your Database or other servers may not handle unlimited requests.
+DevLake does not limit the number of webhook requests. **But be aware** that your Database or other servers may not handle unlimited requests.
## Configuration
-Configuring Webhook via config-ui.
+Configuring webhooks via the Config UI.
-First, You can create a webhook connection.
+First, you can create a webhook connection from the Integration page.
-We suggest that one connection must be used in one system. So you can input the name of your system here.
+We recommand that you give your webhook connection a unique name so that you can identify and manage where you have used it later.
-Then, you can find the webhook URLs here. Copy what you need. (Or copy when you need them)
+After cicking on "Generate POST URL", you will find four webhook URLs. Copy the ones that suits your usage into your CI or issue tracking systems. You can always come back to the webhook page to copy the URLS later on.
@@ -34,15 +34,15 @@ Then, you can find the webhook URLs here. Copy what you need. (Or copy when you
## Incident / Issue
-If you want to collect issue or incident data from your system, you can use the webhook of issues.
+If you want to collect issue or incident data from your system, you can use the two webhooks for issues.
-There are 2 hooks. **Notice**: `https://sample-url.com/` and `1` should be replaced with your URL and connectionId.
+**Notice**: `https://sample-url.com/` and `1` shown in the screenshot above should be replaced with your URL and connectionId.
-#### Update or Create issues
+#### Update or Create Issues
`POST https://sample-url.com/api/plugins/webhook/1/issues`
-Need to be called when an issue or incident is created. The body includes columns as follows:
+needs to be called when an issue or incident is created. The body includes columns as follows:
```
board_key: issue belongs to which board/project
@@ -74,11 +74,11 @@ component(Optional): which component is this issue in.
-#### Close issue (Optional)
+#### Close Issues (Optional)
`POST https://sample-url.com/api/plugins/webhook/1/issue/:boardKey/:issueId/close`
-Need to be called when an issue or incident is closed. Replace `:boardKey` and `:issueId` with specific strings and keep the body empty.
+needs to be called when an issue or incident is closed. Replace `:boardKey` and `:issueId` with specific strings and keep the body empty.
@@ -98,11 +98,11 @@ curl http://127.0.0.1:4000/api/plugins/webhook/1/issue/DLK/DLK-1234/close -X 'PO
Read more in Swagger: http://localhost:4000/api/swagger/index.html#/plugins%2Fwebhook/post_plugins_webhook__connectionId_issues.
-## Deployment
+## Deployments
Adding pipeline webhook in your deploy shells will help you collect data into DevLake.
-First, let us know there are 2 entities Tasks and Pipelines. A pipeline means one build or deployment, and a pipeline may have more than one task.
+First, let us know there are two entities: Tasks and Pipelines. A pipeline means one build or deployment, and a pipeline may have more than one task.
@@ -112,21 +112,21 @@ For example, we can find 6 tasks like `golangci-lint` and `unit-test` in one Git
-(Example 2. Picture from the Internet)
+(Example 2. Image from the Internet)
In Example 2, we can find 12 Jenkins pipelines.
-(Example 3. Picture from the Internet)
+(Example 3. Image from the Internet)
In Example 3, we can find 5 Jenkins pipelines, and these pipelines have 1~4 task(s).
-After figuring out `pipeline` and `task`, we can start to add webhook. 2 hooks need to be added in shells. **Notice**: `https://sample-url.com/` and `1` should be replaced with your URL and connectionId.
+After figuring out `pipeline` and `task`, we can start to add webhooks. Two hooks need to be added in shells. **Notice**: `https://sample-url.com/` and `1` should be replaced with your URL and connectionId.
-#### Update or Create the tasks in the pipeline
+#### Update or Create Tasks in the Pipeline
This hook should be added when the task starts and finishes. So in Example 3, we need to add 8 CURLs in the 4 tasks.
@@ -150,7 +150,7 @@ commit_sha(Optional)
-#### Close pipelines
+#### Close Pipelines
`POST https://sample-url.com/api/plugins/webhook/1/cicd_pipeline/:pipelineName/finish`