You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@devlake.apache.org by ab...@apache.org on 2022/12/26 12:27:20 UTC
[incubator-devlake-website] branch main updated (f1fe8f815 -> 351cc5ea6)
This is an automated email from the ASF dual-hosted git repository.
abeizn pushed a change to branch main
in repository https://gitbox.apache.org/repos/asf/incubator-devlake-website.git
from f1fe8f815 docs: update config ui v0.15.0 images (#362)
new 262e67da4 docs: update webhook v0.15.0 docs
new 95464341d docs: update webhook v0.15.0 docs
new 351cc5ea6 docs: update webhook v0.15.0 docs
The 3 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 | 223 ++++++++++-----------
docs/UserManuals/ConfigUI/webhook.md | 25 ++-
.../img/ConfigUI/webhook-add-data-connections.png | Bin 0 -> 20756 bytes
static/img/ConfigUI/webhook-use.png | Bin 0 -> 92069 bytes
4 files changed, 127 insertions(+), 121 deletions(-)
create mode 100644 static/img/ConfigUI/webhook-add-data-connections.png
create mode 100644 static/img/ConfigUI/webhook-use.png
[incubator-devlake-website] 01/03: docs: update webhook v0.15.0 docs
Posted by ab...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
abeizn pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/incubator-devlake-website.git
commit 262e67da44fa589e46d45c5720d9b35e98902296
Author: abeizn <zi...@merico.dev>
AuthorDate: Fri Dec 23 15:29:46 2022 +0800
docs: update webhook v0.15.0 docs
---
docs/Plugins/webhook.md | 208 +++++++++------------
docs/UserManuals/ConfigUI/webhook.md | 19 +-
.../img/ConfigUI/webhook-add-data-connections.png | Bin 0 -> 20756 bytes
static/img/ConfigUI/webhook-use.png | Bin 0 -> 92069 bytes
4 files changed, 106 insertions(+), 121 deletions(-)
diff --git a/docs/Plugins/webhook.md b/docs/Plugins/webhook.md
index 44de68b87..90f33d529 100644
--- a/docs/Plugins/webhook.md
+++ b/docs/Plugins/webhook.md
@@ -4,50 +4,35 @@ description: >
Webhook Plugin
---
-## Overview
+## Summary
-Incoming Webhooks are your solution to bring data to Apache DevLake when there isn't a specific plugin ready for your DevOps tool. An Incoming Webhook allows users to actively push data to DevLake.
+Incoming Webhooks are your solution to bring data to Apache DevLake when there isn't a specific plugin ready for your DevOps tool. An Incoming Webhook allows users to actively push data to DevLake.
When you create an Incoming Webhook within DevLake, DevLake generates a unique URL. You can then post JSON payloads to this URL to push data directly to your DevLake instance.
In v0.14+, users can push "incidents" and "deployments" required by DORA metrics to DevLake via Incoming Webhooks.
-## Creating webhooks in DevLake
+## Configuration
-### Add a new webhook
-To add a new webhook, go to the "Data Connections" page in config-ui and select "Issue/Deployment Incoming/Webhook".
-
+- Configuring Webhook via [Config UI](/UserManuals/ConfigUI/webhook.md)
-We recommend that you give your webhook connection a unique name so that you can identify and manage where you have used it later.
+## API Sample Request
-After clicking on the "Generate POST URL" button, you will find several webhook URLs. You can then post to these URLs from your CI/CD tool or issue tracking system to push data directly to DevLake. You can always come back to the webhook page to access the URLs later.
+### Deployment
-
-
-### Put webhook on the internet
-
-For the new webhook to work, it needs to be accessible from the DevOps tools from which you would like to push data to DevLake. If DevLake is deployed in your private network and your DevOps tool (e.g. CircleCI) is a cloud service that lives outside of your private network, then you need to make DevLake's webhook accessible to the outside cloud service.
-
-There're many tools for this:
-
- - For testing and quick setup, [ngrok](https://ngrok.com/) is a useful utility that provides a publicly accessible web URL to any locally hosted application. You can put DevLake's webhook on the internet within 5 mins by following ngrok's [Getting Started](https://ngrok.com/docs/getting-started) guide. Note that, when posting to webhook, you may need to replace the `localhost` part in the webhook URL with the forwarding URL that ngrok provides.
- - If you prefer DIY, please checkout open-source reverse proxies like [fatedier/frp](https://github.com/fatedier/frp) or go for the classic [nginx](https://www.nginx.com/).
-
-
-## Register a deployment
+#### Register a deployment
You can copy the generated deployment curl commands to your CI/CD script to post deployments to Apache DevLake. Below is the detailed payload schema:
-| Key | Required | Notes |
-| :---------: | :------: | ------------------------------------------------------------ |
-| commit_sha | ✔️ Yes | the sha of the deployment commit |
-| repo_url | ✔️ Yes | the repo URL of the deployment commit |
-| environment | ✖️ No | the environment this deployment happens. For example, `PRODUCTION` `STAGING` `TESTING` `DEVELOPMENT`. <br/>The default value is `PRODUCTION` |
-| start_time | ✖️ No | Time. Eg. 2020-01-01T12:00:00+00:00<br/> No default value.|
-| end_time | ✖️ No | Time. Eg. 2020-01-01T12:00:00+00:00<br/>The default value is the time when DevLake receives the POST request.|
-
+| Key | Required | Notes |
+| :---------: | :------: | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| commit_sha | ✔️ Yes | the sha of the deployment commit |
+| repo_url | ✔️ Yes | the repo URL of the deployment commit |
+| environment | ✖️ No | the environment this deployment happens. For example, `PRODUCTION` `STAGING` `TESTING` `DEVELOPMENT`. <br/>The default value is `PRODUCTION` |
+| start_time | ✖️ No | Time. Eg. 2020-01-01T12:00:00+00:00<br/> No default value. |
+| end_time | ✖️ No | Time. Eg. 2020-01-01T12:00:00+00:00<br/>The default value is the time when DevLake receives the POST request. |
-### Deployment - Sample API Calls
+#### Deployment - Sample API Calls
Sample CURL to post deployments to DevLake. The following command should be replaced with the actual curl command copied from your Config UI:
@@ -62,6 +47,7 @@ curl https://sample-url.com/api/plugins/webhook/1/deployments -X 'POST' -d '{
```
If you have set a [username/password](https://devlake.apache.org/docs/UserManuals/Authentication) for Config UI, you'll need to add them to the curl command to register a `deployment`:
+
```
curl https://sample-url.com/api/plugins/webhook/1/deployments -X 'POST' -u 'username:password' -d '{
"commit_sha":"015e3d3b480e417aede5a1293bd61de9b0fd051d",
@@ -72,111 +58,100 @@ curl https://sample-url.com/api/plugins/webhook/1/deployments -X 'POST' -u 'user
}'
```
-Read more in [Swagger](https://sample-url.com/api/swagger/index.html#/plugins%2Fwebhook/post_plugins_webhook__connectionId_deployments).
-
-
-
#### Deployment - A real-world example in CircleCI
The following demo shows how to post "deployments" to DevLake from CircleCI. In this example, the CircleCI job 'deploy' is used to manage deployments.
+```
+version: 2.1
+
+jobs:
+ build:
+ docker:
+ - image: cimg/base:stable
+ steps:
+ - checkout
+ - run:
+ name: "build"
+ command: |
+ echo Hello, World!
+
+ deploy:
+ docker:
+ - image: cimg/base:stable
+ steps:
+ - checkout
+ - run:
+ name: "deploy"
+ command: |
+ # The time a deploy started
+ start_time=`date '+%Y-%m-%dT%H:%M:%S%z'`
+
+ # Some deployment tasks here ...
+ echo Hello, World!
+
+ # Send the request to DevLake after deploy
+ # The values start with a '$CIRCLE_' are CircleCI's built-in variables
+ curl https://sample-url.com/api/plugins/webhook/1/deployments -X 'POST' -d "{
+ \"commit_sha\":\"$CIRCLE_SHA1\",
+ \"repo_url\":\"$CIRCLE_REPOSITORY_URL\",
+ \"start_time\":\"$start_time\"
+ }"
+
+workflows:
+ build_and_deploy_workflow:
+ jobs:
+ - build
+ - deploy
+```
- ```
- version: 2.1
-
- jobs:
- build:
- docker:
- - image: cimg/base:stable
- steps:
- - checkout
- - run:
- name: "build"
- command: |
- echo Hello, World!
-
- deploy:
- docker:
- - image: cimg/base:stable
- steps:
- - checkout
- - run:
- name: "deploy"
- command: |
- # The time a deploy started
- start_time=`date '+%Y-%m-%dT%H:%M:%S%z'`
-
- # Some deployment tasks here ...
- echo Hello, World!
-
- # Send the request to DevLake after deploy
- # The values start with a '$CIRCLE_' are CircleCI's built-in variables
- curl https://sample-url.com/api/plugins/webhook/1/deployments -X 'POST' -d "{
- \"commit_sha\":\"$CIRCLE_SHA1\",
- \"repo_url\":\"$CIRCLE_REPOSITORY_URL\",
- \"start_time\":\"$start_time\"
- }"
-
- workflows:
- build_and_deploy_workflow:
- jobs:
- - build
- - deploy
- ```
-
-
-
-## Incident / Issue
+### Incident / Issue
-If you want to collect issue or incident data from your system, you can use the two webhooks for issues.
+If you want to collect issue or incident data from your system, you can use the two webhooks for issues.
#### Update or Create Issues
`POST https://sample-url.com/api/plugins/webhook/1/issues`
-needs to be called when an issue or incident is created. The body should be a JSON and include columns as follows:
-
-| Keyname | Required | Notes |
-| :-----------------------: | :------: | ------------------------------------------------------------ |
-| board_key | ✔️ Yes | issue belongs to which board/project |
-| url | ✖️ No | issue's URL |
-| issue_key | ✔️ Yes | issue's key, needs to be unique in a connection |
-| title | ✔️ Yes | |
-| description | ✖️ No | |
-| epic_key | ✖️ No | in which epic. |
-| type | ✖️ No | type, such as bug/incident/epic/... |
-| status | ✔️ Yes | issue's status. Must be one of `TODO` `DONE` `IN_PROGRESS` |
-| original_status | ✔️ Yes | status in your system, such as created/open/closed/... |
-| story_point | ✖️ No | |
-| resolution_date | ✖️ No | date, Format should be 2020-01-01T12:00:00+00:00 |
-| created_date | ✔️ Yes | date, Format should be 2020-01-01T12:00:00+00:00 |
-| updated_date | ✖️ No | date, Format should be 2020-01-01T12:00:00+00:00 |
-| lead_time_minutes | ✖️ No | how long from this issue accepted to develop |
-| parent_issue_key | ✖️ No | |
-| priority | ✖️ No | |
-| original_estimate_minutes | ✖️ No | |
-| time_spent_minutes | ✖️ No | |
-| time_remaining_minutes | ✖️ No | |
-| creator_id | ✖️ No | the user id of the creator |
-| creator_name | ✖️ No | the user name of the creator, it will just be used to display |
-| assignee_id | ✖️ No | |
-| assignee_name | ✖️ No | |
-| severity | ✖️ No | |
-| component | ✖️ No | which component is this issue in. |
+needs to be called when an issue or incident is created. The body should be a JSON and include columns as follows:
+
+| Keyname | Required | Notes |
+| :-----------------------: | :------: | ------------------------------------------------------------- |
+| board_key | ✔️ Yes | issue belongs to which board/project |
+| url | ✖️ No | issue's URL |
+| issue_key | ✔️ Yes | issue's key, needs to be unique in a connection |
+| title | ✔️ Yes | |
+| description | ✖️ No | |
+| epic_key | ✖️ No | in which epic. |
+| type | ✖️ No | type, such as bug/incident/epic/... |
+| status | ✔️ Yes | issue's status. Must be one of `TODO` `DONE` `IN_PROGRESS` |
+| original_status | ✔️ Yes | status in your system, such as created/open/closed/... |
+| story_point | ✖️ No | |
+| resolution_date | ✖️ No | date, Format should be 2020-01-01T12:00:00+00:00 |
+| created_date | ✔️ Yes | date, Format should be 2020-01-01T12:00:00+00:00 |
+| updated_date | ✖️ No | date, Format should be 2020-01-01T12:00:00+00:00 |
+| lead_time_minutes | ✖️ No | how long from this issue accepted to develop |
+| parent_issue_key | ✖️ No | |
+| priority | ✖️ No | |
+| original_estimate_minutes | ✖️ No | |
+| time_spent_minutes | ✖️ No | |
+| time_remaining_minutes | ✖️ No | |
+| creator_id | ✖️ No | the user id of the creator |
+| creator_name | ✖️ No | the user name of the creator, it will just be used to display |
+| assignee_id | ✖️ No | |
+| assignee_name | ✖️ No | |
+| severity | ✖️ No | |
+| component | ✖️ No | which component is this issue in. |
More information about these columns at [DomainLayerIssueTracking](https://devlake.apache.org/docs/DataModels/DevLakeDomainLayerSchema#domain-1---issue-tracking).
-
-
#### Close Issues (Optional)
`POST https://sample-url.com/api/plugins/webhook/1/issue/:boardKey/:issueId/close`
needs to be called when an issue or incident is closed. Replace `:boardKey` and `:issueId` with specific strings and keep the body empty.
-
-
-### Issues Sample API Calls
+#### Issues Sample API Calls
Sample CURL for Issue Creating :
@@ -190,5 +165,6 @@ 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: https://sample-url.com/api/swagger/index.html#/plugins%2Fwebhook/post_plugins_webhook__connectionId_issues.
+## References
+- [references](/DeveloperManuals/DeveloperSetup.md#references)
diff --git a/docs/UserManuals/ConfigUI/webhook.md b/docs/UserManuals/ConfigUI/webhook.md
index 8ce485e49..7e0f3a20c 100644
--- a/docs/UserManuals/ConfigUI/webhook.md
+++ b/docs/UserManuals/ConfigUI/webhook.md
@@ -4,21 +4,30 @@ sidebar_position: 7
description: Config UI instruction for Webhook
---
-Visit the config-ui via the Domain Name or IP Address and Port,
+Visit config-ui: `http://localhost:4000`.
-### Add a new incoming webhook
-
+### Step 1 - Add Data Connections
+
+
#### Webhook name
+
We recommend that you give your webhook connection a unique name so that you can identify and manage where you have used it later.
### Use Webhooks
+
After clicking on "Generate POST URL", you will find four webhook URLs. Copy the ones that suit your usage into your CI or issue-tracking systems. You can always come back to the webhook page to copy the URLs later on.
-
+
+
+### Put webhook on the internet
+
+For the new webhook to work, it needs to be accessible from the DevOps tools from which you would like to push data to DevLake. If DevLake is deployed in your private network and your DevOps tool (e.g. CircleCI) is a cloud service that lives outside of your private network, then you need to make DevLake's webhook accessible to the outside cloud service.
-For more usage: [plugins/webhook](/Plugins/webhook.md).
+There're many tools for this:
+- For testing and quick setup, [ngrok](https://ngrok.com/) is a useful utility that provides a publicly accessible web URL to any locally hosted application. You can put DevLake's webhook on the internet within 5 mins by following ngrok's [Getting Started](https://ngrok.com/docs/getting-started) guide. Note that, when posting to webhook, you may need to replace the `localhost` part in the webhook URL with the forwarding URL that ngrok provides.
+- If you prefer DIY, please checkout open-source reverse proxies like [fatedier/frp](https://github.com/fatedier/frp) or go for the classic [nginx](https://www.nginx.com/).
## Troubleshooting
diff --git a/static/img/ConfigUI/webhook-add-data-connections.png b/static/img/ConfigUI/webhook-add-data-connections.png
new file mode 100644
index 000000000..895a23d51
Binary files /dev/null and b/static/img/ConfigUI/webhook-add-data-connections.png differ
diff --git a/static/img/ConfigUI/webhook-use.png b/static/img/ConfigUI/webhook-use.png
new file mode 100644
index 000000000..88a3866ca
Binary files /dev/null and b/static/img/ConfigUI/webhook-use.png differ
[incubator-devlake-website] 02/03: docs: update webhook v0.15.0 docs
Posted by ab...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
abeizn pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/incubator-devlake-website.git
commit 95464341dbd4965015c42304050aa81d5265c5e3
Author: abeizn <zi...@merico.dev>
AuthorDate: Mon Dec 26 14:57:45 2022 +0800
docs: update webhook v0.15.0 docs
---
docs/Plugins/webhook.md | 33 +++++++++++++++++++++++++++------
docs/UserManuals/ConfigUI/webhook.md | 10 +++++-----
2 files changed, 32 insertions(+), 11 deletions(-)
diff --git a/docs/Plugins/webhook.md b/docs/Plugins/webhook.md
index 90f33d529..ffe92ce89 100644
--- a/docs/Plugins/webhook.md
+++ b/docs/Plugins/webhook.md
@@ -12,15 +12,36 @@ When you create an Incoming Webhook within DevLake, DevLake generates a unique U
In v0.14+, users can push "incidents" and "deployments" required by DORA metrics to DevLake via Incoming Webhooks.
+## Entities
+
+Check out the [Incoming Webhooks entities](/Overview/SupportedDataSources.md#data-collection-scope-by-each-plugin) collected by this plugin.
+
+## Metrics
+
+Metrics that can be calculated based on the data collected from Incoming Webhooks:
+
+- [Requirement Delivery Rate](/Metrics/RequirementDeliveryRate.md)
+- [Requirement Granularity](/Metrics/RequirementGranularity.md)
+- [Bug Age](/Metrics/BugAge.md)
+- [Bug Count per 1k Lines of Code](/Metrics/BugCountPer1kLinesOfCode.md)
+- [Incident Age](/Metrics/IncidentAge.md)
+- [Incident Count per 1k Lines of Code](/Metrics/IncidentCountPer1kLinesOfCode.md)
+- [DORA - Deployment Frequency](/Metrics/DeploymentFrequency.md)
+- [DORA - Lead Time for Changes](/Metrics/LeadTimeForChanges.md)
+- [DORA - Median Time to Restore Service](/Metrics/MTTR.md)
+- [DORA - Change Failure Rate](/Metrics/CFR.md)
+
## Configuration
-- Configuring Webhook via [Config UI](/UserManuals/ConfigUI/webhook.md)
+- Configuring Incoming Webhooks via [Config UI](/UserManuals/ConfigUI/webhook.md)
## API Sample Request
### Deployment
-#### Register a deployment
+If you want to collect deployment data from your system, you can use the incoming webhooks for deployment.
+
+#### Payload Schema
You can copy the generated deployment curl commands to your CI/CD script to post deployments to Apache DevLake. Below is the detailed payload schema:
@@ -32,7 +53,7 @@ You can copy the generated deployment curl commands to your CI/CD script to post
| start_time | ✖️ No | Time. Eg. 2020-01-01T12:00:00+00:00<br/> No default value. |
| end_time | ✖️ No | Time. Eg. 2020-01-01T12:00:00+00:00<br/>The default value is the time when DevLake receives the POST request. |
-#### Deployment - Sample API Calls
+#### Register a Deployment - Sample API Calls
Sample CURL to post deployments to DevLake. The following command should be replaced with the actual curl command copied from your Config UI:
@@ -109,7 +130,7 @@ workflows:
If you want to collect issue or incident data from your system, you can use the two webhooks for issues.
-#### Update or Create Issues
+#### Register Issues - Update or Create Issues
`POST https://sample-url.com/api/plugins/webhook/1/issues`
@@ -145,13 +166,13 @@ needs to be called when an issue or incident is created. The body should be a JS
More information about these columns at [DomainLayerIssueTracking](https://devlake.apache.org/docs/DataModels/DevLakeDomainLayerSchema#domain-1---issue-tracking).
-#### Close Issues (Optional)
+#### Register Issues - Close Issues (Optional)
`POST https://sample-url.com/api/plugins/webhook/1/issue/:boardKey/:issueId/close`
needs to be called when an issue or incident is closed. Replace `:boardKey` and `:issueId` with specific strings and keep the body empty.
-#### Issues Sample API Calls
+#### Register Issues - Sample API Calls
Sample CURL for Issue Creating :
diff --git a/docs/UserManuals/ConfigUI/webhook.md b/docs/UserManuals/ConfigUI/webhook.md
index 7e0f3a20c..a4a9eda9b 100644
--- a/docs/UserManuals/ConfigUI/webhook.md
+++ b/docs/UserManuals/ConfigUI/webhook.md
@@ -6,21 +6,21 @@ description: Config UI instruction for Webhook
Visit config-ui: `http://localhost:4000`.
-### Step 1 - Add Data Connections
+### Step 1 - Add a new incoming webhook
-
+Users can go to 'Data Connections' to achieve webhook data connections configure.
-#### Webhook name
+
We recommend that you give your webhook connection a unique name so that you can identify and manage where you have used it later.
-### Use Webhooks
+### Step 2 - Use Webhooks
After clicking on "Generate POST URL", you will find four webhook URLs. Copy the ones that suit your usage into your CI or issue-tracking systems. You can always come back to the webhook page to copy the URLs later on.
-### Put webhook on the internet
+#### Put webhook on the internet
For the new webhook to work, it needs to be accessible from the DevOps tools from which you would like to push data to DevLake. If DevLake is deployed in your private network and your DevOps tool (e.g. CircleCI) is a cloud service that lives outside of your private network, then you need to make DevLake's webhook accessible to the outside cloud service.
[incubator-devlake-website] 03/03: docs: update webhook v0.15.0 docs
Posted by ab...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
abeizn pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/incubator-devlake-website.git
commit 351cc5ea6b04f64761fedc4840804f134838a783
Author: abeizn <zi...@merico.dev>
AuthorDate: Mon Dec 26 20:23:07 2022 +0800
docs: update webhook v0.15.0 docs
---
docs/Plugins/webhook.md | 2 +-
docs/UserManuals/ConfigUI/webhook.md | 6 +++---
2 files changed, 4 insertions(+), 4 deletions(-)
diff --git a/docs/Plugins/webhook.md b/docs/Plugins/webhook.md
index ffe92ce89..e11d6dd84 100644
--- a/docs/Plugins/webhook.md
+++ b/docs/Plugins/webhook.md
@@ -79,7 +79,7 @@ curl https://sample-url.com/api/plugins/webhook/1/deployments -X 'POST' -u 'user
}'
```
-#### Deployment - A real-world example in CircleCI
+#### A real-world example - Push CircleCI deployments to DevLake
The following demo shows how to post "deployments" to DevLake from CircleCI. In this example, the CircleCI job 'deploy' is used to manage deployments.
diff --git a/docs/UserManuals/ConfigUI/webhook.md b/docs/UserManuals/ConfigUI/webhook.md
index a4a9eda9b..9616feab9 100644
--- a/docs/UserManuals/ConfigUI/webhook.md
+++ b/docs/UserManuals/ConfigUI/webhook.md
@@ -4,11 +4,11 @@ sidebar_position: 7
description: Config UI instruction for Webhook
---
-Visit config-ui: `http://localhost:4000`.
+Visit config-ui: `http://{localhost}:4000`.
### Step 1 - Add a new incoming webhook
-Users can go to 'Data Connections' to achieve webhook data connections configure.
+Go to the 'Data Connections' page. Create a webhook.
@@ -16,7 +16,7 @@ We recommend that you give your webhook connection a unique name so that you can
### Step 2 - Use Webhooks
-After clicking on "Generate POST URL", you will find four webhook URLs. Copy the ones that suit your usage into your CI or issue-tracking systems. You can always come back to the webhook page to copy the URLs later on.
+Click on Generate POST URL, and you will find four webhook URLs. Copy the ones that suit your usage into your CI or issue-tracking systems. You can always come back to the webhook page to copy the URLs later on.
