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