Get the Slack integration configuration #

GET /integrations/{owner}/configuration/slack

List the Slack channels connected to the organization, with the notification configurations of every product. A channel is connected from the Mergify dashboard; this API cannot connect one.

Authorization (any one of)

Admin Application Key MergifyTokenBearerAuth GitHub Token

Path Parameters

owner string required

The owner of the repository

min length: 1 · max length: 40 · pattern: ^[a-zA-Z0-9\-]+$

Responses

200 Successful Response

channelsSlackNotificationChannelConfiguration[]required

The Slack channels connected to the organization

idstring <uuid>required

The ID of the Slack channel configuration

slack_channelstringrequired

The Slack channel the notifications are posted to

slack_team_namestring | nullrequired

The name of the Slack workspace the channel belongs to

disabled_atstring <date-time> | nullrequired

When Mergify stopped being able to post to this channel. Null while the channel receives notifications.

disabled_reason"webhook_gone" | "oauth_revoked" | nullrequired

Why Mergify cannot post to this channel anymore. Null while the channel receives notifications.

merge_queue_configsMergeQueueNotificationConfiguration[]required

The `merge_queue_notification` configurations of the channel

idstring <uuid>required

The ID of the notification configuration

repositoriesSlackNotificationRepository[]required

The repositories this configuration notifies about. Empty means every repository of the organization.

idintegerrequired

The ID of the repository

ownerGitHubAccountrequired

The owner of the repository

loginstringrequired

idintegerrequired

avatar_urlstring | null

namestringrequired

The name of the repository

full_namestringrequired

The full name of the repository, `owner/name`

eventsMergeQueueNotificationEvent[]required

The merge queue events posted to the channel, each with the outcomes it posts. Empty means every event.

The merge queue event

Enum: action.assign action.backport action.close action.comment action.copy action.delete_head_branch action.dequeue action.dismiss_reviews action.edit action.github_actions action.label action.label.loop_stopped action.merge action.post_check action.queue.batch_bisection_end action.queue.batch_bisection_start action.queue.batch_composition action.queue.change action.queue.checks.change action.queue.checks_end action.queue.checks_postponed action.queue.checks_start action.queue.conflict_deferred action.queue.enter action.queue.leave action.queue.merged action.rebase action.refresh action.request_reviews action.review action.squash action.update ci_insights.auto_quarantine.disabled ci_insights.auto_quarantine.enabled ci_insights.auto_quarantine.modified ci_insights.job_retried command.dequeue command.queue pipeline.create pipeline.delete pipeline.update product.disabled product.enabled queue.pause.create queue.pause.delete queue.pause.update scheduled_freeze.create scheduled_freeze.delete scheduled_freeze.update test.dequarantined test.health.changed test.quarantined

outcomes("success" | "failure" | "pending" | "neutral")[]

The outcomes of this event to post, among those it can have. A request may leave it empty for every outcome; a response always lists them.

"success" | "failure" | "pending" | "neutral"

ci_insights_configsCiInsightsNotificationConfiguration[]required

The `ci_insights_notification` configurations of the channel

idstring <uuid>required

The ID of the notification configuration

repositoriesSlackNotificationRepository[]required

The repositories this configuration notifies about. Empty means every repository of the organization.

idintegerrequired

The ID of the repository

ownerGitHubAccountrequired

The owner of the repository

loginstringrequired

idintegerrequired

avatar_urlstring | null

namestringrequired

The name of the repository

full_namestringrequired

The full name of the repository, `owner/name`

branchesstring[]required

The branches whose CI jobs are reported. Empty means every branch.

pipeline_namesstring[]required

The CI pipelines whose jobs are reported. Empty means every pipeline.

job_namesstring[]required

The CI jobs that are reported. Empty means every job.

The job conclusions that are reported. Empty means every conclusion.

test_quarantine_configsTestQuarantineNotificationConfiguration[]required

The `test_quarantine_notification` configurations of the channel

idstring <uuid>required

The ID of the notification configuration

repositoriesSlackNotificationRepository[]required

The repositories this configuration notifies about. Empty means every repository of the organization.

idintegerrequired

The ID of the repository

ownerGitHubAccountrequired

The owner of the repository

loginstringrequired

idintegerrequired

avatar_urlstring | null

namestringrequired

The name of the repository

full_namestringrequired

The full name of the repository, `owner/name`

event_types("test.quarantined" | "test.dequarantined" | "test.health.changed")[]required

The test events posted to the channel. Empty means every event except `test.health.changed`, which is posted only when listed.

health_from_states("healthy" | "flaky" | "broken")[]required

The health states a test leaves for its `test.health.changed` event to be posted. Empty means every state.

"healthy" | "flaky" | "broken"

health_to_states("healthy" | "flaky" | "broken")[]required

The health states a test enters for its `test.health.changed` event to be posted. Empty means every state.

"healthy" | "flaky" | "broken"

merge_queue_event_possible_outcomesobjectrequired

The outcomes each Merge Queue event can have, which a notification can narrow it to.

Example Response

                          {
  "channels": [
    {
      "id": "efb5681e-7906-4ee9-843b-42e956052987",
      "slack_team_name": "My Slack Team",
      "slack_channel": "#notification",
      "disabled_at": "2024-01-15T10:30:00Z",
      "disabled_reason": "webhook_gone",
      "merge_queue_configs": [
        {
          "id": "cc363671-e816-44a5-ba68-b92391fcdaec",
          "repositories": [
            {
              "id": 123,
              "name": "my-repo",
              "owner": {
                "id": 234,
                "login": "me",
                "type": "User"
              },
              "full_name": "me/my-repo"
            }
          ],
          "events": [
            {
              "type": "scheduled_freeze.create",
              "outcomes": []
            }
          ]
        }
      ],
      "ci_insights_configs": [],
      "test_quarantine_configs": []
    }
  ],
  "merge_queue_event_possible_outcomes": {
    "action.queue.leave": [
      "success",
      "failure",
      "neutral"
    ],
    "scheduled_freeze.create": [
      "neutral"
    ]
  }
}

403 Forbidden

404 Not found

409 Conflict

422 Unprocessable entity

Example Request

curl -X GET "https://api.mergify.com/v1/integrations/:owner/configuration/slack" \
  -H "Authorization: Bearer <token>"

Disconnect a Slack channel #

DELETE /integrations/{owner}/configuration/slack/{channel_configuration_id}

Disconnect a Slack channel from the organization, with every notification configuration it holds

Authorization (any one of)

Admin Application Key MergifyTokenBearerAuth GitHub Token

Path Parameters

channel_configuration_id string <uuid> required

The ID of the Slack channel configuration

owner string required

The owner of the repository

min length: 1 · max length: 40 · pattern: ^[a-zA-Z0-9\-]+$

Responses

204 No Content

403 Forbidden

404 Not found

409 Conflict

422 Unprocessable entity

Example Request

curl -X DELETE "https://api.mergify.com/v1/integrations/:owner/configuration/slack/:channel_configuration_id" \
  -H "Authorization: Bearer <token>"

Create a Slack notification configuration #

POST /integrations/{owner}/configuration/slack/{channel_configuration_id}/{product}

Create a notification configuration for a product on a connected Slack channel. The request body and the response follow the schema of `product`.

Authorization (any one of)

Admin Application Key MergifyTokenBearerAuth GitHub Token

Path Parameters

channel_configuration_id string <uuid> required

The ID of the Slack channel configuration

owner string required

The owner of the repository

min length: 1 · max length: 40 · pattern: ^[a-zA-Z0-9\-]+$

product "merge_queue_notification" | "test_quarantine_notification" | "ci_insights_notification" required

The product the notification configuration is for

Request Body

Variant 1

repositoriesstring[]

The names of the organization's repositories to notify about. Empty means every repository of the organization.

eventsMergeQueueNotificationEvent[] | null

The merge queue events posted to the channel, each with the outcomes it posts. Empty means every event. Required.

The merge queue event

Enum: action.assign action.backport action.close action.comment action.copy action.delete_head_branch action.dequeue action.dismiss_reviews action.edit action.github_actions action.label action.label.loop_stopped action.merge action.post_check action.queue.batch_bisection_end action.queue.batch_bisection_start action.queue.batch_composition action.queue.change action.queue.checks.change action.queue.checks_end action.queue.checks_postponed action.queue.checks_start action.queue.conflict_deferred action.queue.enter action.queue.leave action.queue.merged action.rebase action.refresh action.request_reviews action.review action.squash action.update ci_insights.auto_quarantine.disabled ci_insights.auto_quarantine.enabled ci_insights.auto_quarantine.modified ci_insights.job_retried command.dequeue command.queue pipeline.create pipeline.delete pipeline.update product.disabled product.enabled queue.pause.create queue.pause.delete queue.pause.update scheduled_freeze.create scheduled_freeze.delete scheduled_freeze.update test.dequarantined test.health.changed test.quarantined

outcomes("success" | "failure" | "pending" | "neutral")[]

The outcomes of this event to post, among those it can have. A request may leave it empty for every outcome; a response always lists them.

"success" | "failure" | "pending" | "neutral"

Variant 2

repositoriesstring[]

The names of the organization's repositories to notify about. Empty means every repository of the organization.

branchesstring[]

The branches whose CI jobs are reported. Empty means every branch.

pipeline_namesstring[]

The CI pipelines whose jobs are reported. Empty means every pipeline.

job_namesstring[]

The CI jobs that are reported. Empty means every job.

The job conclusions that are reported. Empty means every conclusion.

Variant 3

repositoriesstring[]

The names of the organization's repositories to notify about. Empty means every repository of the organization.

event_types("test.quarantined" | "test.dequarantined" | "test.health.changed")[]

The test events posted to the channel. Empty means every event except `test.health.changed`, which is posted only when listed.

health_from_states("healthy" | "flaky" | "broken")[]

The health states a test leaves for its `test.health.changed` event to be posted. Empty means every state.

"healthy" | "flaky" | "broken"

health_to_states("healthy" | "flaky" | "broken")[]

The health states a test enters for its `test.health.changed` event to be posted. Empty means every state.

"healthy" | "flaky" | "broken"

Responses

201 Created

Variant 1

idstring <uuid>required

The ID of the notification configuration

repositoriesSlackNotificationRepository[]required

The repositories this configuration notifies about. Empty means every repository of the organization.

idintegerrequired

The ID of the repository

ownerGitHubAccountrequired

The owner of the repository

loginstringrequired

idintegerrequired

avatar_urlstring | null

namestringrequired

The name of the repository

full_namestringrequired

The full name of the repository, `owner/name`

eventsMergeQueueNotificationEvent[]required

The merge queue events posted to the channel, each with the outcomes it posts. Empty means every event.

The merge queue event

Enum: action.assign action.backport action.close action.comment action.copy action.delete_head_branch action.dequeue action.dismiss_reviews action.edit action.github_actions action.label action.label.loop_stopped action.merge action.post_check action.queue.batch_bisection_end action.queue.batch_bisection_start action.queue.batch_composition action.queue.change action.queue.checks.change action.queue.checks_end action.queue.checks_postponed action.queue.checks_start action.queue.conflict_deferred action.queue.enter action.queue.leave action.queue.merged action.rebase action.refresh action.request_reviews action.review action.squash action.update ci_insights.auto_quarantine.disabled ci_insights.auto_quarantine.enabled ci_insights.auto_quarantine.modified ci_insights.job_retried command.dequeue command.queue pipeline.create pipeline.delete pipeline.update product.disabled product.enabled queue.pause.create queue.pause.delete queue.pause.update scheduled_freeze.create scheduled_freeze.delete scheduled_freeze.update test.dequarantined test.health.changed test.quarantined

outcomes("success" | "failure" | "pending" | "neutral")[]

The outcomes of this event to post, among those it can have. A request may leave it empty for every outcome; a response always lists them.

"success" | "failure" | "pending" | "neutral"

Variant 2

idstring <uuid>required

The ID of the notification configuration

repositoriesSlackNotificationRepository[]required

The repositories this configuration notifies about. Empty means every repository of the organization.

idintegerrequired

The ID of the repository

ownerGitHubAccountrequired

The owner of the repository

loginstringrequired

idintegerrequired

avatar_urlstring | null

namestringrequired

The name of the repository

full_namestringrequired

The full name of the repository, `owner/name`

branchesstring[]required

The branches whose CI jobs are reported. Empty means every branch.

pipeline_namesstring[]required

The CI pipelines whose jobs are reported. Empty means every pipeline.

job_namesstring[]required

The CI jobs that are reported. Empty means every job.

The job conclusions that are reported. Empty means every conclusion.

Variant 3

idstring <uuid>required

The ID of the notification configuration

repositoriesSlackNotificationRepository[]required

The repositories this configuration notifies about. Empty means every repository of the organization.

idintegerrequired

The ID of the repository

ownerGitHubAccountrequired

The owner of the repository

loginstringrequired

idintegerrequired

avatar_urlstring | null

namestringrequired

The name of the repository

full_namestringrequired

The full name of the repository, `owner/name`

event_types("test.quarantined" | "test.dequarantined" | "test.health.changed")[]required

The test events posted to the channel. Empty means every event except `test.health.changed`, which is posted only when listed.

health_from_states("healthy" | "flaky" | "broken")[]required

The health states a test leaves for its `test.health.changed` event to be posted. Empty means every state.

"healthy" | "flaky" | "broken"

health_to_states("healthy" | "flaky" | "broken")[]required

The health states a test enters for its `test.health.changed` event to be posted. Empty means every state.

"healthy" | "flaky" | "broken"

Example Response

                          {
  "id": "cc363671-e816-44a5-ba68-b92391fcdaec",
  "repositories": [
    {
      "id": 123,
      "name": "my-repo",
      "owner": {
        "id": 234,
        "login": "me",
        "type": "User"
      },
      "full_name": "me/my-repo"
    }
  ],
  "events": [
    {
      "type": "scheduled_freeze.create",
      "outcomes": []
    }
  ]
}

403 Forbidden

404 Not Found

409 Conflict

422 Unprocessable entity

Example Request

curl -X POST "https://api.mergify.com/v1/integrations/:owner/configuration/slack/:channel_configuration_id/:product" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
  "repositories": [
    "string"
  ],
  "events": [
    {
      "type": "action.assign",
      "outcomes": null
    }
  ]
}'

Update a Slack notification configuration #

PUT /integrations/{owner}/configuration/slack/{channel_configuration_id}/{product}/{notification_configuration_id}

Replace a notification configuration of a connected Slack channel. The request body follows the schema of `product`, and a field left out is reset to empty.

Authorization (any one of)

Admin Application Key MergifyTokenBearerAuth GitHub Token

Path Parameters

channel_configuration_id string <uuid> required

The ID of the Slack channel configuration

notification_configuration_id string <uuid> required

The ID of the Slack notification configuration

owner string required

The owner of the repository

min length: 1 · max length: 40 · pattern: ^[a-zA-Z0-9\-]+$

product "merge_queue_notification" | "test_quarantine_notification" | "ci_insights_notification" required

The product the notification configuration is for

Request Body

Variant 1

repositoriesstring[]

The names of the organization's repositories to notify about. Empty means every repository of the organization.

eventsMergeQueueNotificationEvent[] | null

The merge queue events posted to the channel, each with the outcomes it posts. Empty means every event. Required.

The merge queue event

Enum: action.assign action.backport action.close action.comment action.copy action.delete_head_branch action.dequeue action.dismiss_reviews action.edit action.github_actions action.label action.label.loop_stopped action.merge action.post_check action.queue.batch_bisection_end action.queue.batch_bisection_start action.queue.batch_composition action.queue.change action.queue.checks.change action.queue.checks_end action.queue.checks_postponed action.queue.checks_start action.queue.conflict_deferred action.queue.enter action.queue.leave action.queue.merged action.rebase action.refresh action.request_reviews action.review action.squash action.update ci_insights.auto_quarantine.disabled ci_insights.auto_quarantine.enabled ci_insights.auto_quarantine.modified ci_insights.job_retried command.dequeue command.queue pipeline.create pipeline.delete pipeline.update product.disabled product.enabled queue.pause.create queue.pause.delete queue.pause.update scheduled_freeze.create scheduled_freeze.delete scheduled_freeze.update test.dequarantined test.health.changed test.quarantined

outcomes("success" | "failure" | "pending" | "neutral")[]

The outcomes of this event to post, among those it can have. A request may leave it empty for every outcome; a response always lists them.

"success" | "failure" | "pending" | "neutral"

Variant 2

repositoriesstring[]

The names of the organization's repositories to notify about. Empty means every repository of the organization.

branchesstring[]

The branches whose CI jobs are reported. Empty means every branch.

pipeline_namesstring[]

The CI pipelines whose jobs are reported. Empty means every pipeline.

job_namesstring[]

The CI jobs that are reported. Empty means every job.

The job conclusions that are reported. Empty means every conclusion.

Variant 3

repositoriesstring[]

The names of the organization's repositories to notify about. Empty means every repository of the organization.

event_types("test.quarantined" | "test.dequarantined" | "test.health.changed")[]

The test events posted to the channel. Empty means every event except `test.health.changed`, which is posted only when listed.

health_from_states("healthy" | "flaky" | "broken")[]

The health states a test leaves for its `test.health.changed` event to be posted. Empty means every state.

"healthy" | "flaky" | "broken"

health_to_states("healthy" | "flaky" | "broken")[]

The health states a test enters for its `test.health.changed` event to be posted. Empty means every state.

"healthy" | "flaky" | "broken"

Responses

204 No Content

403 Forbidden

404 Not Found

409 Conflict

422 Unprocessable entity

Example Request

curl -X PUT "https://api.mergify.com/v1/integrations/:owner/configuration/slack/:channel_configuration_id/:product/:notification_configuration_id" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
  "repositories": [
    "string"
  ],
  "events": [
    {
      "type": "action.assign",
      "outcomes": null
    }
  ]
}'

Delete a Slack notification configuration #

DELETE /integrations/{owner}/configuration/slack/{channel_configuration_id}/{product}/{notification_configuration_id}

Delete a notification configuration from a connected Slack channel

Authorization (any one of)

Admin Application Key MergifyTokenBearerAuth GitHub Token

Path Parameters

channel_configuration_id string <uuid> required

The ID of the Slack channel configuration

notification_configuration_id string <uuid> required

The ID of the Slack notification configuration

product "merge_queue_notification" | "test_quarantine_notification" | "ci_insights_notification" required

The product the notification configuration is for

owner string required

The owner of the repository

min length: 1 · max length: 40 · pattern: ^[a-zA-Z0-9\-]+$

Responses

204 No Content

403 Forbidden

404 Not Found

409 Conflict

422 Unprocessable entity

Example Request

curl -X DELETE "https://api.mergify.com/v1/integrations/:owner/configuration/slack/:channel_configuration_id/:product/:notification_configuration_id" \
  -H "Authorization: Bearer <token>"

Send a test Slack notification #

POST /integrations/{owner}/configuration/slack/{channel_configuration_id}/{product}/{notification_configuration_id}/test

Post a clearly-labeled test message to the configured Slack channel to validate delivery

Authorization (any one of)

Admin Application Key MergifyTokenBearerAuth GitHub Token

Path Parameters

channel_configuration_id string <uuid> required

The ID of the Slack channel configuration

notification_configuration_id string <uuid> required

The ID of the Slack notification configuration

product "merge_queue_notification" | "test_quarantine_notification" | "ci_insights_notification" required

The product the notification configuration is for

owner string required

The owner of the repository

min length: 1 · max length: 40 · pattern: ^[a-zA-Z0-9\-]+$

Responses

204 No Content

402 The organization's plan does not include the Slack integration

403 Forbidden

404 Not Found

409 Conflict

422 Unprocessable entity

502 Slack delivery failed

Example Request

curl -X POST "https://api.mergify.com/v1/integrations/:owner/configuration/slack/:channel_configuration_id/:product/:notification_configuration_id/test" \
  -H "Authorization: Bearer <token>"

Scopes

CI Setup

Flaky tests

Test Frameworks Setup

Compare Tools

Actions

Reference

Reference

GitHub Actions

Integrations

Integrations endpoints for the Mergify API.

Get the Slack integration configuration #

Disconnect a Slack channel #

Create a Slack notification configuration #

Update a Slack notification configuration #

Delete a Slack notification configuration #

Send a test Slack notification #