SupportConsoleDevelopersStart a trialContact

Chapter 11. Notifications overview

Notifications in Red Hat Quay alert you about repository events such as pushes, builds, and image expiry. You can configure delivery methods for users, teams, or organizations.

11.1. Notification actions
Copy link

Notification actions in Red Hat Quay define how event alerts are delivered. You can send notices by email, webhook, Flowdock, HipChat, or Slack.

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.

11.1.1. E-mail notifications
Copy link

E-mails are sent to specified addresses that describe the specified event. E-mail addresses must be verified on a per-repository basis.

11.1.2. Webhook POST notifications
Copy link

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.

11.1.3. Flowdock notifications
Copy link

Posts a message to Flowdock.

11.1.4. Hipchat notifications
Copy link

Posts a message to HipChat.

11.1.5. Slack notifications
Copy link

Posts a message to Slack.

11.2. Creating notifications by using the UI
Copy link

To alert users to repository events such as pushes or build failures, you can create a notification from the Settings page in the Red Hat Quay v2 UI. You select an event trigger and a delivery method, such as email or Slack.

Prerequisites

  • You have created a repository.
  • You have administrative privileges for the repository.

Procedure

  1. Navigate to a repository on Red Hat Quay.
  2. In the navigation pane, click Settings.
  3. In the Events and Notifications category, click Create Notification to add a new notification for a repository event. The Create notification popup box appears.

  4. 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

  5. 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.

  6. After selecting an event and notification method, click Create Notification.

11.2.1. Creating an image expiration notification
Copy link

To create an image expiration notification in Red Hat Quay, you can use the v2 UI or the API. You set how many days before expiry to send the alert.

Triggers can work in conjunction with the auto-pruning feature. You can also create this notification 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

  1. On the Red Hat Quay v2 UI, click Repositories.
  2. Select the name of a repository.
  3. Click Settings Events and notifications.
  4. Click Create notification. The Create notification popup box appears.
  5. Click the Select event…​ box, then click Image expiry trigger.
  6. 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.

  7. In the Select method…​ box, click one of the following:

    • E-mail
    • Webhook POST
    • Flowdock Team Notification
    • HipChat Room Notification
    • Slack Notification
  8. Depending on which method you chose, include the necessary data. For example, if you chose Webhook POST, include the Webhook URL.
  9. Optional. Provide a POST JSON body template.
  10. Optional. Provide a Title for your notification.
  11. Click Submit. You are returned to the Events and notifications page, and the notification now appears.

  12. 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

    where:

    NOTIFICATION_TASK_RUN_MINIMUM_INTERVAL_MINUTES
    Specifies that by default, this field is set to 300, or 5 hours.

Verification

  1. 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

  2. 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"
}

11.3. Creating notifications by using the API
Copy link

To create, test, reset, or delete repository notifications in Red Hat Quay, you can use the repository notification API endpoints.

Prerequisites

  • You have created a repository.
  • You have administrative privileges for the repository.
  • You have created an OAuth access token.

Procedure

  1. Enter the following POST /api/v1/repository/{repository}/notification command to create a notification on your repository: 

    $ 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}

  2. You can test your repository notification by entering the following POST /api/v1/repository/{repository}/notification/{uuid}/test command: 

    $ curl -X POST \
  -H "Authorization: Bearer <bearer_token>" \
  https://<quay-server.example.com>/api/v1/repository/<repository>/notification/<uuid>/test

    Example output

    {}

  3. You can reset repository notification failures to 0 by entering the following POST /api/v1/repository/{repository}/notification/{uuid} command: 

    $ curl -X POST \
  -H "Authorization: Bearer <bearer_token>" \
  https://<quay-server.example.com>/api/v1/repository/<repository>/notification/<uuid>

  4. Enter the following DELETE /api/v1/repository/{repository}/notification/{uuid} command to delete a repository notification: 

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

    $ 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": []}

To create quota warning or error notifications for organization and user namespaces in Red Hat Quay, you can use the API. Warning limits trigger quota_warning events and reject limits trigger quota_error events.

Warning-type quota limits trigger quota_warning notifications. Reject-type quota limits trigger quota_error notifications. For organization email notifications, "config": {} is valid because recipients are resolved server-side (organization contact email, or organization administrators if unset). User email notifications are sent to the user account email address.

Red Hat Quay throttles repeated alerts for the same namespace and threshold by using QUOTA_NOTIFICATION_COOLDOWN_SECONDS (default: 86400 / 24 hours). If usage drops below a threshold and later crosses it again, the notification can re-fire. Deleting a quota also removes associated quota_warning and quota_error notification rules for that namespace.

Prerequisites

  • You have created an OAuth access token.
  • FEATURE_QUOTA_MANAGEMENT is enabled in your Red Hat Quay configuration.
  • FEATURE_QUOTA_NOTIFICATIONS is enabled in your Red Hat Quay configuration.
  • Optional: You have established quota limits for your organization or user namespace. You can create notification rules before setting quota limits. Notifications trigger automatically after quotas are configured and thresholds are crossed.
  • You have administrative privileges for the namespace.

Procedure

  1. To create an organization quota notification, enter a command similar to the following example: 

    $ curl -X POST \
-H "Authorization: Bearer <bearer_token>" \
-H "Content-Type: application/json" \
--data '{
    "event": "quota_warning",
    "method": "email",
    "config": {},
    "eventConfig": {}
}' \
https://<quay-server.example.com>/api/v1/organization/<orgname>/notifications

    Example output

    {
"uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"title": null,
"event": "quota_warning",
"method": "email",
"config": {},
"event_config": {},
"number_of_failures": 0
}

  2. Optional: You can create a quota error notification by changing the event type. To complete this task, run a command similar to the following example: 

    $ curl -X POST \
-H "Authorization: Bearer <bearer_token>" \
-H "Content-Type: application/json" \
--data '{
    "event": "quota_error",
    "method": "slack",
    "config": {
    "url": "https://hooks.slack.com/services/YOUR/SLACK/WEBHOOK"
    },
    "eventConfig": {}
}' \
https://<quay-server.example.com>/api/v1/organization/<orgname>/notifications

  3. To create a user namespace quota notification, enter a command similar to the following example: 

    $ curl -X POST \
-H "Authorization: Bearer <bearer_token>" \
-H "Content-Type: application/json" \
--data '{
    "event": "quota_warning",
    "method": "email",
    "config": {},
    "eventConfig": {}
}' \
https://<quay-server.example.com>/api/v1/user/namespacenotifications

To route quota notification emails to a shared organization contact address in Red Hat Quay, you can set the organization contact email with the API. You can list and test notifications for organizations and user namespaces.

Procedure

  1. Set the organization contact email by entering a command similar to the following example: 

    $ curl -X PUT \
-H "Authorization: Bearer <bearer_token>" \
-H "Content-Type: application/json" \
--data '{
    "email": "ops-team@example.com"
}' \
https://<quay-server.example.com>/api/v1/organization/<orgname>
    Note

    Setting the organization contact email requires organization administrator permissions (org:admin scope). If a contact email is not set, quota notifications default to sending to organization administrator email addresses.

  2. List all notifications for an organization by entering a command similar to the following example: 

    $ curl -X GET \
-H "Authorization: Bearer <bearer_token>" \
-H "Accept: application/json" \
https://<quay-server.example.com>/api/v1/organization/<orgname>/notifications

    Example output

    {
"notifications": [
    {
    "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "title": null,
    "event": "quota_warning",
    "method": "email",
    "config": {},
    "event_config": {},
    "number_of_failures": 0
    }
]
}

  3. List all notifications for your user namespace by entering a command similar to the following example: 

    $ curl -X GET \
-H "Authorization: Bearer <bearer_token>" \
-H "Accept: application/json" \
https://<quay-server.example.com>/api/v1/user/namespacenotifications

  4. To test a notification, enter a command similar to the following example: 

    $ curl -X POST \
-H "Authorization: Bearer <bearer_token>" \
https://<quay-server.example.com>/api/v1/organization/<orgname>/notifications/<uuid>/test

    Example output

    {}

    Note

    For email notifications, if an organization contact email is set, the test notification is routed to that address. Otherwise, email notifications default to organization administrators. For Slack, webhook, and other methods, routing follows the notification config.

11.6. Resetting notification failures
Copy link

You can resume delivery on a notification channel that has been automatically suspended because of repeated endpoint failures. To do this, reset the failure counter to zero after resolving the underlying connectivity issue.

Procedure

  1. To reset an organization notification failure count to 0, enter a command similar to the following example: 

    $ curl -X POST \
-H "Authorization: Bearer <bearer_token>" \
https://<quay-server.example.com>/api/v1/organization/<orgname>/notifications/<uuid>

    A successful request returns HTTP 204 with an empty body.

  2. To reset a user namespace notification failure count to 0, enter a command similar to the following example: 

    $ curl -X POST \
-H "Authorization: Bearer <bearer_token>" \
https://<quay-server.example.com>/api/v1/user/namespacenotifications/<uuid>

    A successful request returns HTTP 204 with an empty body.

11.7. Deleting quota notifications
Copy link

To stop tracking storage thresholds or remove an inactive alerting endpoint in Red Hat Quay, you can delete quota notifications from organization or user namespaces.

Note

Deleting a namespace quota also automatically deletes associated quota_warning and quota_error notification rules for that namespace. After you recreate a quota, you must create new notification rules.

Procedure

  1. Delete an organization notification by entering a command similar to the following example: 

    $ curl -X DELETE \
-H "Authorization: Bearer <bearer_token>" \
https://<quay-server.example.com>/api/v1/organization/<orgname>/notifications/<uuid>

  2. Delete a user notification by entering a command similar to the following example: 

    $ curl -X DELETE \
-H "Authorization: Bearer <bearer_token>" \
https://<quay-server.example.com>/api/v1/user/namespacenotifications/<uuid>

Verification

  1. Verify that the notification was deleted. List notifications with the following command: 

    $ curl -X GET \
-H "Authorization: Bearer <bearer_token>" \
-H "Accept: application/json" \
https://<quay-server.example.com>/api/v1/organization/<orgname>/notifications

    Example output

    {"notifications": []}

11.8. Repository events description
Copy link

Repository events in Red Hat Quay describe the triggers that can generate notifications. You can use these event types when you configure alerts.

11.8.1. Repository Push
Copy link

A successful push of one or more images was made to the repository: 

{
  "name": "repository",
  "repository": "dgangaia/test",
  "namespace": "dgangaia",
  "docker_url": "quay.io/dgangaia/test",
  "homepage": "https://quay.io/repository/dgangaia/repository",
  "updated_tags": [
    "latest"
  ]
}

11.8.2. Dockerfile Build Queued
Copy link

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. 

{
  "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"
}

11.8.3. Dockerfile Build started
Copy link

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. 

{
  "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"
}

11.8.4. Dockerfile Build successfully completed
Copy link

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. 

{
  "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"
  ]
}

11.8.5. Dockerfile Build failed
Copy link

The following example is a response from a Dockerfile Build that has failed. 

{
  "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"
}

11.8.6. Dockerfile Build cancelled
Copy link

The following example is a response from a Dockerfile Build that has been cancelled. 

{
  "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"
}

11.8.7. Vulnerability detected
Copy link

The following example is a response from a Dockerfile Build has detected a vulnerability in the repository. 

{
  "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
  }
}
Red Hat logoGithubRedditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust. Explore our recent updates.

Legal Notice

Theme

© 2026 Red HatBack to top