Unblu logo

Endpoints

Main endpoint

POST <server url>/ucascade/merge-request

This is the principal endpoint, that receive the Merge Request Webhook event sent by GitLab.

Requests are processed asynchronously, meaning that GitLab will receive a 202 Accepted response back immediately.

Example:

{
  "build_commit" : "6af21ad",
  "build_timestamp" : "2022-01-01T07:21:58.378413Z",
  "gitlab_event_uuid" : "62940263-b495-4f7e-b0e8-578c7307f13d"
}

  • build_commit and build_timestamp allow you to identify the ucascade version.

  • gitlab_event_uuid is the value received in the X-Gitlab-Event-UUID header.

Blocking endpoint

A secondary endpoint where the process in done in a blocking way is available as well:

POST <server url>/ucascade/merge-request-blocking

With this blocking endpoint the different actions made by ucascade (see Technical documentation) are visible in the returned response.

Example:

{
  "build_commit" : "6af21ad",
  "build_timestamp" : "2022-01-01T07:21:58.378413Z",
  "gitlab_event_uuid" : "62940263-b495-4f7e-b0e8-578c7307f13d",
  "previous_auto_mr_merged" : {
    "id" : 34,
    "project_id" : 1,
    "mr_number" : 34,
    "title" : "[ucascade] Auto MR: 'main/1.2.x' -> 'main/1.3.x' (!29)",
    "description" : "Automatic cascade merge request: `test` !29 --> `main/1.2.x` --> `main/1.3.x`",
    "state" : "opened",
    "detailed_merge_status" : "mergeable",
    "has_conflicts" : false,
    "source_branch" : "mr29_main/1.2.x",
    "target_branch" : "main/1.3.x",
    "web_url" : "https://gitlab.example.com/root/some-project/-/merge_requests/34",
    "ucascade_state" : "MERGED"
  },
  "created_auto_mr" : {
    "id" : 38,
    "project_id" : 1,
    "mr_number" : 38,
    "assignee_ids" : [ 40 ],
    "title" : "[ucascade] Auto MR: 'main/1.3.x' -> 'develop' (!25)",
    "description" : "Automatic cascade merge request: `test` !24 --> `main/1.2.x` !25 --> `main/1.3.x` --> develop",
    "state" : "opened",
    "detailed_merge_status" : "broken_status",
    "has_conflicts" : true,
    "source_branch" : "mr25_main/1.3.x",
    "target_branch" : "main",
    "web_url" : "https://gitlab.example.com/root/some-project/-/merge_requests/38",
    "ucascade_state" : "NOT_MERGED_CONFLICTS"
  },
  "existing_branch_deleted" : {
    "branch_name" : "mr21_main/1.2.x"
  }
}

Since GitLab keeps the response obtained when delivering a webhook event and displays it in the webhook admin page, using this endpoint might be interesting for debugging purpose.

Replay endpoint

An additional endpoint is available to trigger the process using some simplified input compared to the merge-request event body sent by the GitLab Webhook API. In this simplified input, the start_commit_sha may correspond to two different things in original merge-request event:

  • To the merge_commit_sha, in case the merge created a merge commit

  • To the last_commit.id in case the fast-forward merge strategy is used (no merge commit)

POST <server url>/ucascade/replay

Body:

{
  "project_id" : 23,
  "mr_number" : 122,
  "user_id" : 9382,
  "source_branch" : "feature/1.3.x/some-change",
  "target_branch" : "main/1.3.x",
  "mr_state" : "merged",
  "start_commit_sha" : "0c6f9d312b924bff313f60db2f269b5f4901cd95",
  "mr_action" : "merge",
  "gitlab_event_uuid" : "replay-394720"
}

The response is the same as in the blocking case.

Using this endpoint is interesting to trigger again the ucascade action for a given event using curl, without having to send the complete webhook event body.

Readiness and liveness probes

The application provides standard probes:

  • <server url>/q/health/live: The application is up and running (liveness).

  • <server url>/q/health/ready: The application is ready to serve requests (readiness).

  • <server url>/q/health: Accumulating all health check procedures in the application.