Skip to content

Commit

Permalink
docs: update webhook docs (#576)
Browse files Browse the repository at this point in the history 
* docs: update webhook docs

* docs: update webhook docs
  • Loading branch information
@abeizn
abeizn authored Jul 10, 2023
1 parent ee13ad5 commit 483cd1f
Show file tree
Hide file tree
Showing 2 changed files with 42 additions and 42 deletions.
42 changes: 21 additions & 21 deletions docs/Plugins/webhook.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -45,25 +45,25 @@ If you want to collect deployment data from your system, you can use the incomin

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 |
| :---------: | :------: | ------------------------------------------------------------ |
| pipeline_id | ✖️ No | related Domain Layer `cicd_pipelines.id` |
| environment | ✖️ No | the environment this deployment happens. For example, `PRODUCTION` `STAGING` `TESTING` `DEVELOPMENT`. <br/>The default value is `PRODUCTION` |
| repo_url | ✔️ Yes | the repo URL of the deployment commit<br />If there is a row in the domain layer table `repos` where `repos.url` equals `repo_url`, the `repoId` will be filled with `repos.id`. |
| repo_id | ✖️ No | related Domain Layer `repos.id` <br/> No default value. |
| ref_name | ✖️ No | related branch/tag<br/> No default value. |
| commit_sha | ✔️ Yes | the sha of the deployment commit |
| create_time | ✖️ No | Time. Eg. 2020-01-01T12:00:00+00:00<br/> No default value. |
| start_time | ✔️ Yes | Time. Eg. 2020-01-01T12:00:00+00:00<br/> No default value. |
| end_time | ✔️ Yes | Time. Eg. 2020-01-01T12:00:00+00:00<br/> The default value is the time when DevLake receives the POST request. |
| result | ✖️ No | deployment result, one of the values : `SUCCESS`, `FAILURE`, `ABORT`, `MANUAL`, <br/> The default value is `SUCCESS`. |
| Key | Required | Notes |
| :---------: | :------: | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| pipeline_id | ✖️ No | related Domain Layer `cicd_pipelines.id` |
| environment | ✖️ No | the environment this deployment happens. For example, `PRODUCTION` `STAGING` `TESTING` `DEVELOPMENT`. <br/>The default value is `PRODUCTION` |
| repo_url | ✔️ Yes | the repo URL of the deployment commit<br />If there is a row in the domain layer table `repos` where `repos.url` equals `repo_url`, the `repoId` will be filled with `repos.id`. |
| repo_id | ✖️ No | related Domain Layer `repos.id` <br/> No default value. |
| ref_name | ✖️ No | related branch/tag<br/> No default value. |
| commit_sha | ✔️ Yes | the sha of the deployment commit |
| create_time | ✖️ No | Time. Eg. 2020-01-01T12:00:00+00:00<br/> No default value. |
| start_time | ✔️ Yes | Time. Eg. 2020-01-01T12:00:00+00:00<br/> No default value. |
| end_time | ✔️ Yes | Time. Eg. 2020-01-01T12:00:00+00:00<br/> The default value is the time when DevLake receives the POST request. |
| result | ✖️ No | deployment result, one of the values : `SUCCESS`, `FAILURE`, `ABORT`, `MANUAL`, <br/> The default value is `SUCCESS`. |

#### 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:

```
curl https://sample-url.com/api/plugins/webhook/1/deployments -X 'POST' -d '{
curl http://localhost:8080/plugins/webhook/1/deployments -X 'POST' -d '{
"pipeline_id": "optional-pipeline-id",
"environment":"PRODUCTION",
"repo_url":"https://github.com/apache/incubator-devlake/",
Expand All @@ -72,15 +72,15 @@ curl https://sample-url.com/api/plugins/webhook/1/deployments -X 'POST' -d '{
"commit_sha":"015e3d3b480e417aede5a1293bd61de9b0fd051d",
"create_time":"2020-01-01T11:00:00+00:00",
"start_time":"2020-01-01T12:00:00+00:00",
"end_time":"2020-01-02T13:00:00+00:00"
"result": "FAILURE",
"end_time":"2020-01-02T13:00:00+00:00",
"result": "FAILURE"
}'
```

If you have set a [username/password](GettingStarted/Authentication.md) 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 '{
curl http://localhost:8080/plugins/webhook/1/deployments -X 'POST' -u 'username:password' -d '{
"commit_sha":"015e3d3b480e417aede5a1293bd61de9b0fd051d",
"repo_url":"https://github.com/apache/incubator-devlake/",
"start_time":"2020-01-01T12:00:00+00:00",
Expand Down Expand Up @@ -122,7 +122,7 @@ jobs:
# 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 "{
curl http://localhost:8080/plugins/webhook/1/deployments -X 'POST' -d "{
\"commit_sha\":\"$CIRCLE_SHA1\",
\"repo_url\":\"$CIRCLE_REPOSITORY_URL\",
\"start_time\":\"$start_time\"
Expand All @@ -141,7 +141,7 @@ If you want to collect issue or incident data from your system, you can use the

#### Register Issues - Update or Create Issues

`POST https://sample-url.com/api/plugins/webhook/1/issues`
`POST http://localhost:8080/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:

Expand Down Expand Up @@ -176,7 +176,7 @@ More information about these columns at [DomainLayerIssueTracking](https://devla

#### Register Issues - Close Issues (Optional)

`POST https://sample-url.com/api/plugins/webhook/1/issue/:issueId/close`
`POST http://localhost:8080/plugins/webhook/1/issue/:issueId/close`

needs to be called when an issue or incident is closed. Replace `:issueId` with specific strings and keep the body empty.

Expand All @@ -185,13 +185,13 @@ needs to be called when an issue or incident is closed. Replace `:issueId` with
Sample CURL for Issue Creating :

```
curl https://sample-url.com/api/plugins/webhook/1/issues -X 'POST' -d '{"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,"creator_id":"user1131","creator_name":"Nick name 1","assignee_id":"user1132","assignee_name":"Nick name 2","severity":"","component":""}'
curl http://localhost:8080/plugins/webhook/1/issues -X 'POST' -d '{"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,"creator_id":"user1131","creator_name":"Nick name 1","assignee_id":"user1132","assignee_name":"Nick name 2","severity":"","component":""}'
```

Sample CURL for Issue Closing:

```
curl http://127.0.0.1:4000/api/plugins/webhook/1/issue/DLK-1234/close -X 'POST'
curl http://localhost:8080/plugins/webhook/1/issue/DLK-1234/close -X 'POST'
```

## References
Expand Down
42 changes: 21 additions & 21 deletions versioned_docs/version-v0.17/Plugins/webhook.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -45,25 +45,25 @@ If you want to collect deployment data from your system, you can use the incomin

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 |
| :---------: | :------: | ------------------------------------------------------------ |
| pipeline_id | ✖️ No | related Domain Layer `cicd_pipelines.id` |
| environment | ✖️ No | the environment this deployment happens. For example, `PRODUCTION` `STAGING` `TESTING` `DEVELOPMENT`. <br/>The default value is `PRODUCTION` |
| repo_url | ✔️ Yes | the repo URL of the deployment commit<br />If there is a row in the domain layer table `repos` where `repos.url` equals `repo_url`, the `repoId` will be filled with `repos.id`. |
| repo_id | ✖️ No | related Domain Layer `repos.id` <br/> No default value. |
| ref_name | ✖️ No | related branch/tag<br/> No default value. |
| commit_sha | ✔️ Yes | the sha of the deployment commit |
| create_time | ✖️ No | Time. Eg. 2020-01-01T12:00:00+00:00<br/> No default value. |
| start_time | ✔️ Yes | Time. Eg. 2020-01-01T12:00:00+00:00<br/> No default value. |
| end_time | ✔️ Yes | Time. Eg. 2020-01-01T12:00:00+00:00<br/> The default value is the time when DevLake receives the POST request. |
| result | ✖️ No | deployment result, one of the values : `SUCCESS`, `FAILURE`, `ABORT`, `MANUAL`, <br/> The default value is `SUCCESS`. |
| Key | Required | Notes |
| :---------: | :------: | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| pipeline_id | ✖️ No | related Domain Layer `cicd_pipelines.id` |
| environment | ✖️ No | the environment this deployment happens. For example, `PRODUCTION` `STAGING` `TESTING` `DEVELOPMENT`. <br/>The default value is `PRODUCTION` |
| repo_url | ✔️ Yes | the repo URL of the deployment commit<br />If there is a row in the domain layer table `repos` where `repos.url` equals `repo_url`, the `repoId` will be filled with `repos.id`. |
| repo_id | ✖️ No | related Domain Layer `repos.id` <br/> No default value. |
| ref_name | ✖️ No | related branch/tag<br/> No default value. |
| commit_sha | ✔️ Yes | the sha of the deployment commit |
| create_time | ✖️ No | Time. Eg. 2020-01-01T12:00:00+00:00<br/> No default value. |
| start_time | ✔️ Yes | Time. Eg. 2020-01-01T12:00:00+00:00<br/> No default value. |
| end_time | ✔️ Yes | Time. Eg. 2020-01-01T12:00:00+00:00<br/> The default value is the time when DevLake receives the POST request. |
| result | ✖️ No | deployment result, one of the values : `SUCCESS`, `FAILURE`, `ABORT`, `MANUAL`, <br/> The default value is `SUCCESS`. |

#### 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:

```
curl https://sample-url.com/api/plugins/webhook/1/deployments -X 'POST' -d '{
curl http://localhost:8080/plugins/webhook/1/deployments -X 'POST' -d '{
"pipeline_id": "optional-pipeline-id",
"environment":"PRODUCTION",
"repo_url":"https://github.com/apache/incubator-devlake/",
Expand All @@ -72,15 +72,15 @@ curl https://sample-url.com/api/plugins/webhook/1/deployments -X 'POST' -d '{
"commit_sha":"015e3d3b480e417aede5a1293bd61de9b0fd051d",
"create_time":"2020-01-01T11:00:00+00:00",
"start_time":"2020-01-01T12:00:00+00:00",
"end_time":"2020-01-02T13:00:00+00:00"
"result": "FAILURE",
"end_time":"2020-01-02T13:00:00+00:00",
"result": "FAILURE"
}'
```

If you have set a [username/password](GettingStarted/Authentication.md) 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 '{
curl http://localhost:8080/plugins/webhook/1/deployments -X 'POST' -u 'username:password' -d '{
"commit_sha":"015e3d3b480e417aede5a1293bd61de9b0fd051d",
"repo_url":"https://github.com/apache/incubator-devlake/",
"start_time":"2020-01-01T12:00:00+00:00",
Expand Down Expand Up @@ -122,7 +122,7 @@ jobs:
# 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 "{
curl http://localhost:8080/plugins/webhook/1/deployments -X 'POST' -d "{
\"commit_sha\":\"$CIRCLE_SHA1\",
\"repo_url\":\"$CIRCLE_REPOSITORY_URL\",
\"start_time\":\"$start_time\"
Expand All @@ -141,7 +141,7 @@ If you want to collect issue or incident data from your system, you can use the

#### Register Issues - Update or Create Issues

`POST https://sample-url.com/api/plugins/webhook/1/issues`
`POST http://localhost:8080/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:

Expand Down Expand Up @@ -176,7 +176,7 @@ More information about these columns at [DomainLayerIssueTracking](https://devla

#### Register Issues - Close Issues (Optional)

`POST https://sample-url.com/api/plugins/webhook/1/issue/:issueId/close`
`POST http://localhost:8080/plugins/webhook/1/issue/:issueId/close`

needs to be called when an issue or incident is closed. Replace `:issueId` with specific strings and keep the body empty.

Expand All @@ -185,13 +185,13 @@ needs to be called when an issue or incident is closed. Replace `:issueId` with
Sample CURL for Issue Creating :

```
curl https://sample-url.com/api/plugins/webhook/1/issues -X 'POST' -d '{"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,"creator_id":"user1131","creator_name":"Nick name 1","assignee_id":"user1132","assignee_name":"Nick name 2","severity":"","component":""}'
curl http://localhost:8080/plugins/webhook/1/issues -X 'POST' -d '{"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,"creator_id":"user1131","creator_name":"Nick name 1","assignee_id":"user1132","assignee_name":"Nick name 2","severity":"","component":""}'
```

Sample CURL for Issue Closing:

```
curl http://127.0.0.1:4000/api/plugins/webhook/1/issue/DLK-1234/close -X 'POST'
curl http://localhost:8080/plugins/webhook/1/issue/DLK-1234/close -X 'POST'
```

## References
Expand Down

0 comments on commit 483cd1f

Please sign in to comment.