You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@devlake.apache.org by GitBox <gi...@apache.org> on 2022/12/23 07:31:35 UTC
[GitHub] [incubator-devlake-website] abeizn opened a new pull request, #357: docs: update webhook v0.15.0 docs
abeizn opened a new pull request, #357:
URL: https://github.com/apache/incubator-devlake-website/pull/357
### ⚠️ Pre Checklist
> Please complete _ALL_ items in this checklist, and remove before submitting
- [ ] I have `npm run build` and `npm run serve` locally before submitting this PR
- [ ] I have read through the [Contributing](https://devlake.apache.org/community/) Documentation
# Summary
<!--
Thanks for submitting a PR! We appreciate you spending the time to work on these changes. Please fill out as many sections below as possible.
-->
### Does this close any open issues?
Closes xx
### Screenshots
Include any relevant screenshots here.
### Other Information
Any other information that is important to this PR.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@devlake.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [incubator-devlake-website] Startrekzky commented on a diff in pull request #357: docs: update webhook v0.15.0 docs
Posted by GitBox <gi...@apache.org>.
Startrekzky commented on code in PR #357:
URL: https://github.com/apache/incubator-devlake-website/pull/357#discussion_r1056305116
##########
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
Review Comment:
1. Keep `Entities` and `Metrics` sections.
2. Add a column `Incoming Webhook` in the `supported date source` doc
##########
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)
Review Comment:
To make it consistent, use incoming webhook, not just webhook.
##########
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
Review Comment:
You can just use 'Add a new incoming webhook' as the title. Tell users to go to 'Data Connections' to achieve this in the description.
##########
docs/Plugins/webhook.md:
##########
@@ -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
Review Comment:
3. A real-world example - Push CircleCI deployments to DevLake
##########
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
Review Comment:
Remove this title.
##########
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
Review Comment:
Please also update the v0.14 configuring webhook doc after this one has been updated.
##########
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
Review Comment:
Add a description under this title to summarize this section.
##########
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
Review Comment:
2. Register a Deployment - Sample API Calls
##########
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
Review Comment:
I suggest adding the link to webhook plugin doc's payload part. Users can not finish the operation by this doc alone.
##########
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
Review Comment:
1. Payload Schema
##########
docs/Plugins/webhook.md:
##########
@@ -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
Review Comment:
Add a title beforehand
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@devlake.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [incubator-devlake-website] abeizn merged pull request #357: docs: update webhook v0.15.0 docs
Posted by GitBox <gi...@apache.org>.
abeizn merged PR #357:
URL: https://github.com/apache/incubator-devlake-website/pull/357
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@devlake.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [incubator-devlake-website] Startrekzky commented on a diff in pull request #357: docs: update webhook v0.15.0 docs
Posted by GitBox <gi...@apache.org>.
Startrekzky commented on code in PR #357:
URL: https://github.com/apache/incubator-devlake-website/pull/357#discussion_r1057214651
##########
docs/Plugins/webhook.md:
##########
@@ -4,50 +4,56 @@ 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
+## Entities
-### Add a new webhook
-To add a new webhook, go to the "Data Connections" page in config-ui and select "Issue/Deployment Incoming/Webhook".
-
+Check out the [Incoming Webhooks entities](/Overview/SupportedDataSources.md#data-collection-scope-by-each-plugin) collected by this plugin.
-We recommend that you give your webhook connection a unique name so that you can identify and manage where you have used it later.
+## Metrics
-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.
+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)
-### Put webhook on the internet
+## Configuration
-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.
+- Configuring Incoming Webhooks via [Config UI](/UserManuals/ConfigUI/webhook.md)
-There're many tools for this:
+## API Sample Request
- - 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/).
+### Deployment
+If you want to collect deployment data from your system, you can use the incoming webhooks for deployment.
Review Comment:
If your CI/CD tools are not listed on the [Supported Data Sources](relative url) page, you can use the incoming webhooks to push deployments to DevLake.
##########
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 a new incoming webhook
+
+Users can go to 'Data Connections' to achieve webhook data connections configure.
Review Comment:
Go to the 'Data Connections' page. Create a webhook.
##########
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 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.
Review Comment:
Click on `Generate POST URL`, and you will find four webhook URLs.
##########
docs/Plugins/webhook.md:
##########
@@ -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
Review Comment:
Can you use this title?
##########
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`.
Review Comment:
`http://{localhost}:4000`
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@devlake.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org