Chapter 10. Notifications overview
Chapter 10. Notifications overview Red Hat Quay supports adding notifications to a repository for various events that occur in the repository's lifecycle. 10.1. Notification actions Notifications are added to the Events and Notifications section of the Repository Settings page. They are also added to the Notifications window, which can be found by clicking the bell icon in the navigation pane of Red Hat Quay. Red Hat Quay notifications can be setup to be sent to a User , Team , or the entire organization . Notifications can be delivered by one of the following methods. E-mail notifications E-mails are sent to specified addresses that describe the specified event. E-mail addresses must be verified on a per-repository basis. Webhook POST notifications An HTTP POST call is made to the specified URL with the event's data. For more information about event data, see "Repository events description". When the URL is HTTPS, the call has an SSL client certificate set from Red Hat Quay. Verification of this certificate proves that the call originated from Red Hat Quay. Responses with the status code in the 2xx range are considered successful. Responses with any other status code are considered failures and result in a retry of the webhook notification. Flowdock notifications Posts a message to Flowdock. Hipchat notifications Posts a message to HipChat. Slack notifications Posts a message to Slack. 10.2. Creating notifications by using the UI Use the following procedure to add notifications. Prerequisites You have created a repository. You have administrative privileges for the repository. Procedure Navigate to a repository on Red Hat Quay. In the navigation pane, click Settings . In the Events and Notifications category, click Create Notification to add a new notification for a repository event. The Create notification popup box appears. On the Create repository popup box, click the When this event occurs box to select an event. You can select a notification for the following types of events: Push to Repository Image build failed Image build queued Image build started Image build success Image build cancelled Image expiry trigger After you have selected the event type, select the notification method. The following methods are supported: Quay Notification E-mail Notification Webhook POST Flowdock Team Notification HipChat Room Notification Slack Notification Depending on the method that you choose, you must include additional information. For example, if you select E-mail , you are required to include an e-mail address and an optional notification title. After selecting an event and notification method, click Create Notification . 10.2.1. Creating an image expiration notification Image expiration event triggers can be configured to notify users through email, Slack, webhooks, and so on, and can be configured at the repository level. Triggers can be set for images expiring in any amount of days, and can work in conjunction with the auto-pruning feature. Image expiration notifications can be set by using the Red Hat Quay v2 UI or by using the createRepoNotification API endpoint. Prerequisites FEATURE_GARBAGE_COLLECTION: true is set in your config.yaml file. Optional. FEATURE_AUTO_PRUNE: true is set in your config.yaml file. Procedure On the Red Hat Quay v2 UI, click Repositories . Select the name of a repository. Click Settings Events and notifications . Click Create notification . The Create notification popup box appears. Click the Select event... box, then click Image expiry trigger . In the When the image is due to expiry in days box, enter the number of days before the image's expiration when you want to receive an alert. For example, use 1 for 1 day. In the Select method... box, click one of the following: E-mail Webhook POST Flowdock Team Notification HipChat Room Notification Slack Notification Depending on which method you chose, include the necessary data. For example, if you chose Webhook POST , include the Webhook URL . Optional. Provide a POST JSON body template . Optional. Provide a Title for your notification. Click Submit . You are returned to the Events and notifications page, and the notification now appears. Optional. You can set the NOTIFICATION_TASK_RUN_MINIMUM_INTERVAL_MINUTES variable in your config.yaml file. with this field set, if there are any expiring images notifications will be sent automatically. By default, this is set to 300 , or 5 hours, however it can be adjusted as warranted. NOTIFICATION_TASK_RUN_MINIMUM_INTERVAL_MINUTES: 300 1 1 By default, this field is set to 300 , or 5 hours. Verification Click the menu kebab Test Notification . The following message is returned: Test Notification Queued A test version of this notification has been queued and should appear shortly Depending on which method you chose, check your e-mail, webhook address, Slack channel, and so on. The information sent should look similar to the following example: { "repository": "sample_org/busybox", "namespace": "sample_org", "name": "busybox", "docker_url": "quay-server.example.com/sample_org/busybox", "homepage": "http://quay-server.example.com/repository/sample_org/busybox", "tags": [ "latest", "v1" ], "expiring_in": "1 days" } 10.3. Creating notifications by using the API Use the following procedure to add notifications. Prerequisites You have created a repository. You have administrative privileges for the repository. You have Created an OAuth access token . You have set BROWSER_API_CALLS_XHR_ONLY: false in your config.yaml file. Procedure Enter the following POST /api/v1/repository/{repository}/notification command to create a notification on your repository: USD curl -X POST \ -H "Authorization: Bearer <bearer_token>" \ -H "Content-Type: application/json" \ --data '{ "event": "<event>", "method": "<method>", "config": { "<config_key>": "<config_value>" }, "eventConfig": { "<eventConfig_key>": "<eventConfig_value>" } }' \ https://<quay-server.example.com>/api/v1/repository/<namespace>/<repository_name>/notification/ This command does not return output in the CLI. Instead, you can enter the following GET /api/v1/repository/{repository}/notification/{uuid} command to obtain information about the repository notification: {"uuid": "240662ea-597b-499d-98bb-2b57e73408d6", "title": null, "event": "repo_push", "method": "quay_notification", "config": {"target": {"name": "quayadmin", "kind": "user", "is_robot": false, "avatar": {"name": "quayadmin", "hash": "b28d563a6dc76b4431fc7b0524bbff6b810387dac86d9303874871839859c7cc", "color": "#17becf", "kind": "user"}}}, "event_config": {}, "number_of_failures": 0} You can test your repository notification by entering the following POST /api/v1/repository/{repository}/notification/{uuid}/test command: USD curl -X POST \ -H "Authorization: Bearer <bearer_token>" \ https://<quay-server.example.com>/api/v1/repository/<repository>/notification/<uuid>/test Example output {} You can reset repository notification failures to 0 by entering the following POST /api/v1/repository/{repository}/notification/{uuid} command: USD curl -X POST \ -H "Authorization: Bearer <bearer_token>" \ https://<quay-server.example.com>/api/v1/repository/<repository>/notification/<uuid> Enter the following DELETE /api/v1/repository/{repository}/notification/{uuid} command to delete a repository notification: USD curl -X DELETE \ -H "Authorization: Bearer <bearer_token>" \ https://<quay-server.example.com>/api/v1/repository/<namespace>/<repository_name>/notification/<uuid> This command does not return output in the CLI. Instead, you can enter the following GET /api/v1/repository/{repository}/notification/ command to retrieve a list of all notifications: USD curl -X GET -H "Authorization: Bearer <bearer_token>" -H "Accept: application/json" https://<quay-server.example.com>/api/v1/repository/<namespace>/<repository_name>/notification Example output {"notifications": []} 10.4. Repository events description The following sections detail repository events. Repository Push A successful push of one or more images was made to the repository: Dockerfile Build Queued The following example is a response from a Dockerfile Build that has been queued into the Build system. Note Responses can differ based on the use of optional attributes. Dockerfile Build started The following example is a response from a Dockerfile Build that has been queued into the Build system. Note Responses can differ based on the use of optional attributes. Dockerfile Build successfully completed The following example is a response from a Dockerfile Build that has been successfully completed by the Build system. Note This event occurs simultaneously with a Repository Push event for the built image or images. Dockerfile Build failed The following example is a response from a Dockerfile Build that has failed. Dockerfile Build cancelled The following example is a response from a Dockerfile Build that has been cancelled. Vulnerability detected The following example is a response from a Dockerfile Build has detected a vulnerability in the repository.
NOTIFICATION_TASK_RUN_MINIMUM_INTERVAL_MINUTES: 300 1 Test Notification Queued A test version of this notification has been queued and should appear shortly { "repository": "sample_org/busybox", "namespace": "sample_org", "name": "busybox", "docker_url": "quay-server.example.com/sample_org/busybox", "homepage": "http://quay-server.example.com/repository/sample_org/busybox", "tags": [ "latest", "v1" ], "expiring_in": "1 days" } curl -X POST -H "Authorization: Bearer <bearer_token>" -H "Content-Type: application/json" --data '{ "event": "<event>", "method": "<method>", "config": { "<config_key>": "<config_value>" }, "eventConfig": { "<eventConfig_key>": "<eventConfig_value>" } }' https://<quay-server.example.com>/api/v1/repository/<namespace>/<repository_name>/notification/ {"uuid": "240662ea-597b-499d-98bb-2b57e73408d6", "title": null, "event": "repo_push", "method": "quay_notification", "config": {"target": {"name": "quayadmin", "kind": "user", "is_robot": false, "avatar": {"name": "quayadmin", "hash": "b28d563a6dc76b4431fc7b0524bbff6b810387dac86d9303874871839859c7cc", "color": "#17becf", "kind": "user"}}}, "event_config": {}, "number_of_failures": 0} curl -X POST -H "Authorization: Bearer <bearer_token>" https://<quay-server.example.com>/api/v1/repository/<repository>/notification/<uuid>/test {} curl -X POST -H "Authorization: Bearer <bearer_token>" https://<quay-server.example.com>/api/v1/repository/<repository>/notification/<uuid> curl -X DELETE -H "Authorization: Bearer <bearer_token>" https://<quay-server.example.com>/api/v1/repository/<namespace>/<repository_name>/notification/<uuid> curl -X GET -H "Authorization: Bearer <bearer_token>" -H "Accept: application/json" https://<quay-server.example.com>/api/v1/repository/<namespace>/<repository_name>/notification {"notifications": []} { "name": "repository", "repository": "dgangaia/test", "namespace": "dgangaia", "docker_url": "quay.io/dgangaia/test", "homepage": "https://quay.io/repository/dgangaia/repository", "updated_tags": [ "latest" ] } { "build_id": "296ec063-5f86-4706-a469-f0a400bf9df2", "trigger_kind": "github", //Optional "name": "test", "repository": "dgangaia/test", "namespace": "dgangaia", "docker_url": "quay.io/dgangaia/test", "trigger_id": "38b6e180-9521-4ff7-9844-acf371340b9e", //Optional "docker_tags": [ "master", "latest" ], "repo": "test", "trigger_metadata": { "default_branch": "master", "commit": "b7f7d2b948aacbe844ee465122a85a9368b2b735", "ref": "refs/heads/master", "git_url": "git@github.com:dgangaia/test.git", "commit_info": { //Optional "url": "https://github.com/dgangaia/test/commit/b7f7d2b948aacbe844ee465122a85a9368b2b735", "date": "2019-03-06T12:48:24+11:00", "message": "adding 5", "author": { //Optional "username": "dgangaia", "url": "https://github.com/dgangaia", //Optional "avatar_url": "https://avatars1.githubusercontent.com/u/43594254?v=4" //Optional }, "committer": { "username": "web-flow", "url": "https://github.com/web-flow", "avatar_url": "https://avatars3.githubusercontent.com/u/19864447?v=4" } } }, "is_manual": false, "manual_user": null, "homepage": "https://quay.io/repository/dgangaia/test/build/296ec063-5f86-4706-a469-f0a400bf9df2" } { "build_id": "a8cc247a-a662-4fee-8dcb-7d7e822b71ba", "trigger_kind": "github", //Optional "name": "test", "repository": "dgangaia/test", "namespace": "dgangaia", "docker_url": "quay.io/dgangaia/test", "trigger_id": "38b6e180-9521-4ff7-9844-acf371340b9e", //Optional "docker_tags": [ "master", "latest" ], "build_name": "50bc599", "trigger_metadata": { //Optional "commit": "50bc5996d4587fd4b2d8edc4af652d4cec293c42", "ref": "refs/heads/master", "default_branch": "master", "git_url": "git@github.com:dgangaia/test.git", "commit_info": { //Optional "url": "https://github.com/dgangaia/test/commit/50bc5996d4587fd4b2d8edc4af652d4cec293c42", "date": "2019-03-06T14:10:14+11:00", "message": "test build", "committer": { //Optional "username": "web-flow", "url": "https://github.com/web-flow", //Optional "avatar_url": "https://avatars3.githubusercontent.com/u/19864447?v=4" //Optional }, "author": { //Optional "username": "dgangaia", "url": "https://github.com/dgangaia", //Optional "avatar_url": "https://avatars1.githubusercontent.com/u/43594254?v=4" //Optional } } }, "homepage": "https://quay.io/repository/dgangaia/test/build/a8cc247a-a662-4fee-8dcb-7d7e822b71ba" } { "build_id": "296ec063-5f86-4706-a469-f0a400bf9df2", "trigger_kind": "github", //Optional "name": "test", "repository": "dgangaia/test", "namespace": "dgangaia", "docker_url": "quay.io/dgangaia/test", "trigger_id": "38b6e180-9521-4ff7-9844-acf371340b9e", //Optional "docker_tags": [ "master", "latest" ], "build_name": "b7f7d2b", "image_id": "sha256:0339f178f26ae24930e9ad32751d6839015109eabdf1c25b3b0f2abf8934f6cb", "trigger_metadata": { "commit": "b7f7d2b948aacbe844ee465122a85a9368b2b735", "ref": "refs/heads/master", "default_branch": "master", "git_url": "git@github.com:dgangaia/test.git", "commit_info": { //Optional "url": "https://github.com/dgangaia/test/commit/b7f7d2b948aacbe844ee465122a85a9368b2b735", "date": "2019-03-06T12:48:24+11:00", "message": "adding 5", "committer": { //Optional "username": "web-flow", "url": "https://github.com/web-flow", //Optional "avatar_url": "https://avatars3.githubusercontent.com/u/19864447?v=4" //Optional }, "author": { //Optional "username": "dgangaia", "url": "https://github.com/dgangaia", //Optional "avatar_url": "https://avatars1.githubusercontent.com/u/43594254?v=4" //Optional } } }, "homepage": "https://quay.io/repository/dgangaia/test/build/296ec063-5f86-4706-a469-f0a400bf9df2", "manifest_digests": [ "quay.io/dgangaia/test@sha256:2a7af5265344cc3704d5d47c4604b1efcbd227a7a6a6ff73d6e4e08a27fd7d99", "quay.io/dgangaia/test@sha256:569e7db1a867069835e8e97d50c96eccafde65f08ea3e0d5debaf16e2545d9d1" ] } { "build_id": "5346a21d-3434-4764-85be-5be1296f293c", "trigger_kind": "github", //Optional "name": "test", "repository": "dgangaia/test", "docker_url": "quay.io/dgangaia/test", "error_message": "Could not find or parse Dockerfile: unknown instruction: GIT", "namespace": "dgangaia", "trigger_id": "38b6e180-9521-4ff7-9844-acf371340b9e", //Optional "docker_tags": [ "master", "latest" ], "build_name": "6ae9a86", "trigger_metadata": { //Optional "commit": "6ae9a86930fc73dd07b02e4c5bf63ee60be180ad", "ref": "refs/heads/master", "default_branch": "master", "git_url": "git@github.com:dgangaia/test.git", "commit_info": { //Optional "url": "https://github.com/dgangaia/test/commit/6ae9a86930fc73dd07b02e4c5bf63ee60be180ad", "date": "2019-03-06T14:18:16+11:00", "message": "failed build test", "committer": { //Optional "username": "web-flow", "url": "https://github.com/web-flow", //Optional "avatar_url": "https://avatars3.githubusercontent.com/u/19864447?v=4" //Optional }, "author": { //Optional "username": "dgangaia", "url": "https://github.com/dgangaia", //Optional "avatar_url": "https://avatars1.githubusercontent.com/u/43594254?v=4" //Optional } } }, "homepage": "https://quay.io/repository/dgangaia/test/build/5346a21d-3434-4764-85be-5be1296f293c" } { "build_id": "cbd534c5-f1c0-4816-b4e3-55446b851e70", "trigger_kind": "github", "name": "test", "repository": "dgangaia/test", "namespace": "dgangaia", "docker_url": "quay.io/dgangaia/test", "trigger_id": "38b6e180-9521-4ff7-9844-acf371340b9e", "docker_tags": [ "master", "latest" ], "build_name": "cbce83c", "trigger_metadata": { "commit": "cbce83c04bfb59734fc42a83aab738704ba7ec41", "ref": "refs/heads/master", "default_branch": "master", "git_url": "git@github.com:dgangaia/test.git", "commit_info": { "url": "https://github.com/dgangaia/test/commit/cbce83c04bfb59734fc42a83aab738704ba7ec41", "date": "2019-03-06T14:27:53+11:00", "message": "testing cancel build", "committer": { "username": "web-flow", "url": "https://github.com/web-flow", "avatar_url": "https://avatars3.githubusercontent.com/u/19864447?v=4" }, "author": { "username": "dgangaia", "url": "https://github.com/dgangaia", "avatar_url": "https://avatars1.githubusercontent.com/u/43594254?v=4" } } }, "homepage": "https://quay.io/repository/dgangaia/test/build/cbd534c5-f1c0-4816-b4e3-55446b851e70" } { "repository": "dgangaia/repository", "namespace": "dgangaia", "name": "repository", "docker_url": "quay.io/dgangaia/repository", "homepage": "https://quay.io/repository/dgangaia/repository", "tags": ["latest", "othertag"], "vulnerability": { "id": "CVE-1234-5678", "description": "This is a bad vulnerability", "link": "http://url/to/vuln/info", "priority": "Critical", "has_fix": true } }