Skip to content

Commit

Permalink
docs: update webhook payloads (#758)
Browse files Browse the repository at this point in the history 
Co-authored-by: Startrekzky <[email protected]>
  • Loading branch information
@Startrekzky @merico-devlake
Startrekzky and merico-devlake authored May 31, 2024
1 parent a9aa707 commit 5478a1b
Show file tree
Hide file tree
Showing 2 changed files with 155 additions and 205 deletions.
179 changes: 77 additions & 102 deletions docs/Plugins/webhook.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -47,100 +47,70 @@ Metrics that can be calculated based on the data collected from Incoming Webhook

### Deployment

If you want to collect deployment data from your system, you can use the incoming webhooks for deployment.
If you want to collect deployment data from your system, you can use the incoming webhooks for deployments.

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

| Key | Required | Notes |
|:------------------:|:--------:|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| pipeline_id | ✔️ Yes | This will be the unique id of table cicd_deployments. This key was optional before v1.0.0-beta8. |
| 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. |
| name | ✖️ No | deployment name. The default value is "deployment for `request.commit_sha`" |
| display_title | ✖️ No | deployment display_title. No default value. |
| ref_name | ✖️ No | related branch/tag<br/> No default value. |
| commit_sha | ✔️ Yes | the sha of the deployment commit |
| commit_msg | ✖️ No | the sha of the deployment commit message |
| create_time | ✖️ No | Time. E.g. 2020-01-01T12:00:00+00:00<br/> No default value. |
| start_time | ✔️ Yes | Time. E.g. 2020-01-01T12:00:00+00:00<br/> No default value. |
| end_time | ✖️ No | Time. E.g. 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`. |
| deployment_commits | ✖ No | Allow deployment webhook to push deployments to multiple repos in one request, includes display_title,repo_url,commit_sha,commit_msg,name,ref_name. |
| id | ✔️ Yes | This will be the unique ID of table cicd_deployments. This key replaced pipeline_id for clarity. |
| createdDate | ✖️ No | Time. E.g. 2020-01-01T12:00:00+00:00<br/> No default value. |
| startedDate | ✔️ Yes | Time. E.g. 2020-01-01T12:00:00+00:00<br/> No default value. |
| finishedDate | ✔️ Yes | Time. E.g. 2020-01-01T12:00:00+00:00<br/> No default value. |
| environment | ✖️ No | The environment this deployment happens. For example, `PRODUCTION` `STAGING` `TESTING` `DEVELOPMENT`. <br/>The default value is `PRODUCTION` |
| result | ✖️ No | deployment result, one of the values : `SUCCESS`, `FAILURE`, `ABORT`, `MANUAL`, <br/> The default value is `SUCCESS`. |
| displayTitle | ✖️ No | A readable title for the deployment. |
| name | ✖️ No | Deprecated. |
| deploymentCommits.repoUrl | ✔️ 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`. |
| deploymentCommits.repoId | ✖️ No | Deprecated. |
| deploymentCommits.refName | ✖️ No | The branch/tag to deploy <br/> No default value. |
| deploymentCommits.commitSha | ✔️ Yes | Commit sha that triggers the deploy in this repo |
| deploymentCommits.commitMsg | ✖️ No | Commit sha of the deployment commit message |
| deploymentCommits.displayTitle | ✖️ No | A readable title for the deployment to this repo. |
| deploymentCommits.name | ✖️ No | Deprecated. |

More information about these columns at the domain layer tables: [cicd_deployments](/DataModels/DevLakeDomainLayerSchema.md#cicd_deployments) and [cicd_deployment_commits](/DataModels/DevLakeDomainLayerSchema.md#cicd_deployment_commits).


#### Register a Deployment - Sample API Calls

To deploy on a single repository, use the following command:
```
curl <devlake-host>/api/rest/plugins/webhook/1/deployments -X 'POST' -d '{
"pipeline_id": "required-pipeline-id",
"environment":"PRODUCTION",
"repo_url":"https://github.com/apache/incubator-devlake/",
"repo_id": "optional-repo-id",
"display_title":"optional-custom-deploy-display-title",
"name": "optional-deployment-name. If you do not post a name, DevLake will generate one for you.",
"ref_name": "optional-release-v0.17",
"commit_sha":"015e3d3b480e417aede5a1293bd61de9b0fd051d",
"commit_msg":"optional-commit-message",
"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"
}'
```
The payload supports the deployment to one or multiple repositories (referring to the [discussion](https://github.com/apache/incubator-devlake/discussions/6162)).

Please replace the `API_KEY` with the real token generated after creating a webhook.

To deploy across multiple repositories (refer to the [discussion](https://github.com/apache/incubator-devlake/discussions/6162)), use the following command:
```
curl <devlake-host>/api/rest/plugins/webhook/1/deployments -X 'POST' -d '{
"pipeline_id": "required-pipeline-id",
curl <devlake-host>/api/rest/plugins/webhook/1/deployments -X 'POST' -H 'Authorization: Bearer {API_KEY}' -d '{
"id": "required-id",
"createdDate":"2020-01-01T11:00:00+00:00",
"startedDate":"2020-01-01T12:00:00+00:00",
"finishedDate":"2020-01-02T13:00:00+00:00",
"environment":"PRODUCTION",
"repo_id": "optional-repo-id",
"display_title":"optional-custom-deploy-display-title",
"name": "optional-deployment-name. If you do not post a name, DevLake will generate one for you.",
"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",
"deployment_commits":[
"displayTitle":"optional-custom-deploy-display-title",
"name": "optional-deployment-name. If you do not post a name, DevLake will generate one for you.",
"deploymentCommits":[
{
"display_title":"optional-custom-deployment-commit-display-title-1",
"repo_url":"repo-1",
"repoUrl":"required-repo-url",
"refName": "optional-release-v0.17",
"commitSha":"c1",
"commitMsg":"optional-msg-1",
"name":"optional, if null, it will be deployment for {commit_sha}",
"ref_name": "optional-release-v0.17",
"commit_sha":"c1",
"commit_msg":"optional-msg-1"
"displayTitle":"optional-custom-deployment-commit-display-title-1"
},
{
"display_title":"optional-custom-deployment-commit-display-title-2",
"repo_url":"repo-2",
"repoUrl":"repo-2",
"refName": "optional-release-v0.17",
"commitSha":"c2",
"commitMsg":"optional-msg-2",
"name":"optional, if null, it will be deployment for {commit_sha}",
"ref_name": "optional-release-v0.17",
"commit_sha":"c2",
"commit_msg":"optional-msg-2"
"displayTitle":"optional-custom-deployment-commit-display-title-2"
}
]
}'
```

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 <devlake-host>/api/rest/plugins/webhook/1/deployments -X 'POST' -u 'username:password' -d '{
"pipeline_id": "required-pipeline-id",
"deployment_commits":[
{
"commit_sha":"the sha of deployment commit1",
"repo_url":"the repo URL of the deployment commit"
}
],
"start_time":"2020-01-01T12:00:00+00:00",
"end_time":"2020-01-02T12:00:00+00:00"
}'
```

#### 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.
Expand Down Expand Up @@ -168,18 +138,23 @@ jobs:
name: "deploy"
command: |
# The time a deploy started
start_time=`date '+%Y-%m-%dT%H:%M:%S%z'`
started_date=`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 <devlake-host>/api/rest/plugins/webhook/1/deployments -X 'POST' -d "{
\"pipeline_id\": \"$PIPLINE_ID\",
\"commit_sha\":\"$CIRCLE_SHA1\",
\"repo_url\":\"$CIRCLE_REPOSITORY_URL\",
\"start_time\":\"$start_time\"
\"id\": \"$PIPELINE_ID\",
\"startedDate\":\"$started_date\",
\"finishedDate\":\"$finished_date\",
\"deploymentCommits\":\[
\{
\"commitSha\":\"$CIRCLE_SHA1\",
\"repoUrl\":\"$CIRCLE_REPOSITORY_URL\",
\}
\]
}"
workflows:
Expand All @@ -201,32 +176,32 @@ needs to be called when an issue or incident is created. The body should be a JS

| Keyname | Required | Notes |
| :-----------------------: | :------: | ------------------------------------------------------------- |
| url | ✖️ No | issue's URL |
| issue_key | ✔️ Yes | issue's key, needs to be unique in a connection |
| url | ✖️ No | Issue's URL |
| issueKey | ✔️ 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 | |
| epicKey | ✖️ No | Issue's epic |
| type | ✖️ No | Type, such as `INCIDENT`, `BUG`, `REQUIREMENT`
| status | ✔️ Yes | Issue's status. Must be one of `TODO` `DONE` `IN_PROGRESS` |
| originalStatus | ✔️ Yes | Status in your tool, such as created/open/closed/... |
| storyPoint | ✖️ No | |
| resolutionDate | ✖️ No | Resolved date, Format should be 2020-01-01T12:00:00+00:00 |
| createdDate | ✔️ Yes | Created date, Format should be 2020-01-01T12:00:00+00:00 |
| updatedDate | ✖️ No | Last updated date, Format should be 2020-01-01T12:00:00+00:00 |
| leadTimeMinutes | ✖️ No | How long from this issue accepted to develop. |
| parentIssueKey | ✖️ 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 | |
| originalEstimateMinutes | ✖️ No | |
| timeSpentMinutes | ✖️ No | |
| timeRemainingMinutes | ✖️ No | |
| creatorId | ✖️ No | The user id of the creator |
| creatorName | ✖️ No | The username of the creator, it will just be used to display |
| assigneeId | ✖️ No | |
| assigneeName | ✖️ No | |
| severity | ✖️ No | |
| component | ✖️ No | which component is this issue in. |
| component | ✖️ No | |

More information about these columns at [DomainLayerIssueTracking](https://devlake.apache.org/docs/DataModels/DevLakeDomainLayerSchema#domain-1---issue-tracking).
More information about these columns at the [domain layer issues table](/DataModels/DevLakeDomainLayerSchema.md#issues).

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

Expand All @@ -240,20 +215,20 @@ Sample CURL for creating an incident:

```
curl <devlake-host>/api/rest/plugins/webhook/1/issues -X 'POST' -d '{
"issue_key":"DLK-1234",
"issueKey":"DLK-1234",
"title":"a feature from DLK",
"description":"",
"url":"",
"type":"INCIDENT",
"status":"TODO",
"created_date":"2020-01-01T12:00:00+00:00",
"updated_date":"2020-01-01T12:00:00+00:00",
"createdDate":"2020-01-01T12:00:00+00:00",
"updatedDate":"2020-01-01T12:00:00+00:00",
"priority":"",
"severity":"",
"creator_id":"user1131",
"creator_name":"Nick name 1",
"assignee_id":"user1132",
"assignee_name":"Nick name 2"
"creatorId":"user1131",
"creatorName":"Nick name 1",
"assigneeId":"user1132",
"assigneeName":"Nick name 2"
}'
```

Expand Down
Loading

0 comments on commit 5478a1b

Please sign in to comment.