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: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
