Document PATCH /api/v2/dora/deployments

.generator/schemas/v2/openapi.yaml

@@ -29346,6 +29346,62 @@ components:
         - service
         - started_at
       type: object
+    DORADeploymentPatchByVersionRequest:
+      description: Request to patch a DORA deployment event identified by service, environment, and version.
+      example:
+        data:
+          attributes:
+            change_failure: true
+            env: "production"
+            remediation:
+              type: "rollback"
+            service: "my-service"
+            version: "v1.2.3"
+          type: "dora_deployment_patch_request"
+      properties:
+        data:
+          $ref: "#/components/schemas/DORADeploymentPatchByVersionRequestData"
+      required:
+        - data
+      type: object
+    DORADeploymentPatchByVersionRequestAttributes:
+      description: Attributes for patching a DORA deployment event identified by service, environment, and version.
+      properties:
+        change_failure:
+          description: Indicates whether the deployment resulted in a change failure.
+          example: true
+          type: boolean
+        env:
+          description: The environment the deployment was performed in.
+          example: production
+          type: string
+        remediation:
+          $ref: "#/components/schemas/DORADeploymentPatchRemediation"
+        service:
+          description: The name of the service that was deployed.
+          example: my-service
+          type: string
+        version:
+          description: "The version deployed. This is the same version used to correlate with [APM Deployment Tracking](https://docs.datadoghq.com/tracing/services/deployment_tracking/)."
+          example: v1.2.3
+          type: string
+      required:
+        - service
+        - env
+        - version
+        - change_failure
+      type: object
+    DORADeploymentPatchByVersionRequestData:
+      description: The JSON:API data for patching a deployment identified by service, environment, and version.
+      properties:
+        attributes:
+          $ref: "#/components/schemas/DORADeploymentPatchByVersionRequestAttributes"
+        type:
+          $ref: "#/components/schemas/DORADeploymentPatchRequestDataType"
+      required:
+        - type
+        - attributes
+      type: object
     DORADeploymentPatchRemediation:
       description: Remediation details for the deployment. Optional, but required to calculate failed deployment recovery time.
       properties:
@@ -139542,6 +139598,52 @@ paths:
         permissions:
           - dora_metrics_write
   /api/v2/dora/deployments:
+    patch:
+      description: |-
+        Update a deployment's change failure status, identifying the deployment by its service, environment, and version instead of its ID. Use this to mark a deployment as a change failure or back to stable. You can optionally include remediation details to enable failed deployment recovery time calculation. If multiple deployments match the given service, environment, and version, the most recently finished one is updated.
+      operationId: PatchDORADeploymentByVersion
+      requestBody:
+        content:
+          application/json:
+            examples:
+              default:
+                value:
+                  data:
+                    attributes:
+                      change_failure: true
+                      env: production
+                      service: my-service
+                      version: v1.2.3
+                    type: dora_deployment_patch_request
+            schema:
+              $ref: "#/components/schemas/DORADeploymentPatchByVersionRequest"
+        required: true
+      responses:
+        "202":
+          description: Accepted
+        "400":
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/JSONAPIErrorResponse"
+          description: Bad Request
+        "403":
+          $ref: "#/components/responses/NotAuthorizedResponse"
+        "429":
+          $ref: "#/components/responses/TooManyRequestsResponse"
+      security:
+        - apiKeyAuth: []
+          appKeyAuth: []
+      summary: Patch a deployment event by version
+      tags: ["DORA Metrics"]
+      x-codegen-request-body-name: body
+      x-permission:
+        operator: OR
+        permissions:
+          - dora_metrics_write
+      x-unstable: |-
+        **Note**: This endpoint is in preview and is subject to change.
+        If you have any feedback, contact [Datadog support](https://docs.datadoghq.com/help/).
     post:
       description: |-
         Use this API endpoint to get a list of deployment events.

examples/v2/dora-metrics/PatchDORADeploymentByVersion.rb

@@ -0,0 +1,23 @@
+# Patch a deployment event by version returns "Accepted" response
+
+require "datadog_api_client"
+DatadogAPIClient.configure do |config|
+  config.unstable_operations["v2.patch_dora_deployment_by_version".to_sym] = true
+end
+api_instance = DatadogAPIClient::V2::DORAMetricsAPI.new
+
+body = DatadogAPIClient::V2::DORADeploymentPatchByVersionRequest.new({
+  data: DatadogAPIClient::V2::DORADeploymentPatchByVersionRequestData.new({
+    attributes: DatadogAPIClient::V2::DORADeploymentPatchByVersionRequestAttributes.new({
+      change_failure: true,
+      env: "production",
+      remediation: DatadogAPIClient::V2::DORADeploymentPatchRemediation.new({
+        type: DatadogAPIClient::V2::DORADeploymentPatchRemediationType::ROLLBACK,
+      }),
+      service: "my-service",
+      version: "v1.2.3",
+    }),
+    type: DatadogAPIClient::V2::DORADeploymentPatchRequestDataType::DORA_DEPLOYMENT_PATCH_REQUEST,
+  }),
+})
+p api_instance.patch_dora_deployment_by_version(body)

features/scenarios_model_mapping.rb

@@ -3219,6 +3219,9 @@
     "v2.DeleteDORADeployment" => {
             "deployment_id" => "String",
     },
+    "v2.PatchDORADeploymentByVersion" => {
+            "body" => "DORADeploymentPatchByVersionRequest",
+    },
     "v2.ListDORADeployments" => {
             "body" => "DORAListDeploymentsRequest",
     },

features/v2/dora_metrics.feature

@@ -148,6 +148,24 @@ Feature: DORA Metrics
     When the request is sent
     Then the response status is 200 OK
 
+  @generated @skip @team:DataDog/ci-app-backend
+  Scenario: Patch a deployment event by version returns "Accepted" response
+    Given a valid "appKeyAuth" key in the system
+    And operation "PatchDORADeploymentByVersion" enabled
+    And new "PatchDORADeploymentByVersion" request
+    And body with value {"data": {"attributes": {"change_failure": true, "env": "production", "remediation": {"type": "rollback"}, "service": "my-service", "version": "v1.2.3"}, "type": "dora_deployment_patch_request"}}
+    When the request is sent
+    Then the response status is 202 Accepted
+
+  @generated @skip @team:DataDog/ci-app-backend
+  Scenario: Patch a deployment event by version returns "Bad Request" response
+    Given a valid "appKeyAuth" key in the system
+    And operation "PatchDORADeploymentByVersion" enabled
+    And new "PatchDORADeploymentByVersion" request
+    And body with value {"data": {"attributes": {"change_failure": true, "env": "production", "remediation": {"type": "rollback"}, "service": "my-service", "version": "v1.2.3"}, "type": "dora_deployment_patch_request"}}
+    When the request is sent
+    Then the response status is 400 Bad Request
+
   @generated @skip @team:DataDog/ci-app-backend
   Scenario: Patch a deployment event returns "Accepted" response
     Given a valid "appKeyAuth" key in the system

features/v2/undo.json

@@ -2374,6 +2374,12 @@
       "type": "idempotent"
     }
   },
+  "PatchDORADeploymentByVersion": {
+    "tag": "DORA Metrics",
+    "undo": {
+      "type": "idempotent"
+    }
+  },
   "ListDORADeployments": {
     "tag": "DORA Metrics",
     "undo": {

lib/datadog_api_client/configuration.rb

@@ -437,6 +437,7 @@ def initialize
             "v2.trigger_deployment_gates_evaluation": false,
             "v2.update_deployment_gate": false,
             "v2.update_deployment_rule": false,
+            "v2.patch_dora_deployment_by_version": false,
             "v2.clone_form": false,
             "v2.create_and_publish_form": false,
             "v2.create_form": false,

lib/datadog_api_client/inflector.rb

@@ -2989,6 +2989,9 @@ def overrides
           "v2.dora_deployment_fetch_response" => "DORADeploymentFetchResponse",
           "v2.dora_deployment_object" => "DORADeploymentObject",
           "v2.dora_deployment_object_attributes" => "DORADeploymentObjectAttributes",
+          "v2.dora_deployment_patch_by_version_request" => "DORADeploymentPatchByVersionRequest",
+          "v2.dora_deployment_patch_by_version_request_attributes" => "DORADeploymentPatchByVersionRequestAttributes",
+          "v2.dora_deployment_patch_by_version_request_data" => "DORADeploymentPatchByVersionRequestData",
           "v2.dora_deployment_patch_remediation" => "DORADeploymentPatchRemediation",
           "v2.dora_deployment_patch_remediation_type" => "DORADeploymentPatchRemediationType",
           "v2.dora_deployment_patch_request" => "DORADeploymentPatchRequest",

lib/datadog_api_client/v2/api/dora_metrics_api.rb

@@ -703,5 +703,78 @@ def patch_dora_deployment_with_http_info(deployment_id, body, opts = {})
       end
       return data, status_code, headers
     end
+
+    # Patch a deployment event by version.
+    #
+    # @see #patch_dora_deployment_by_version_with_http_info
+    def patch_dora_deployment_by_version(body, opts = {})
+      patch_dora_deployment_by_version_with_http_info(body, opts)
+      nil
+    end
+
+    # Patch a deployment event by version.
+    #
+    # Update a deployment's change failure status, identifying the deployment by its service, environment, and version instead of its ID. Use this to mark a deployment as a change failure or back to stable. You can optionally include remediation details to enable failed deployment recovery time calculation. If multiple deployments match the given service, environment, and version, the most recently finished one is updated.
+    #
+    # @param body [DORADeploymentPatchByVersionRequest] 
+    # @param opts [Hash] the optional parameters
+    # @return [Array<(nil, Integer, Hash)>] nil, response status code and response headers
+    def patch_dora_deployment_by_version_with_http_info(body, opts = {})
+      unstable_enabled = @api_client.config.unstable_operations["v2.patch_dora_deployment_by_version".to_sym]
+      if unstable_enabled
+        @api_client.config.logger.warn format("Using unstable operation '%s'", "v2.patch_dora_deployment_by_version")
+      else
+        raise DatadogAPIClient::APIError.new(message: format("Unstable operation '%s' is disabled", "v2.patch_dora_deployment_by_version"))
+      end
+
+      if @api_client.config.debugging
+        @api_client.config.logger.debug 'Calling API: DORAMetricsAPI.patch_dora_deployment_by_version ...'
+      end
+      # verify the required parameter 'body' is set
+      if @api_client.config.client_side_validation && body.nil?
+        fail ArgumentError, "Missing the required parameter 'body' when calling DORAMetricsAPI.patch_dora_deployment_by_version"
+      end
+      # resource path
+      local_var_path = '/api/v2/dora/deployments'
+
+      # query parameters
+      query_params = opts[:query_params] || {}
+
+      # header parameters
+      header_params = opts[:header_params] || {}
+      # HTTP header 'Accept' (if needed)
+      header_params['Accept'] = @api_client.select_header_accept(['*/*'])
+      # HTTP header 'Content-Type'
+      header_params['Content-Type'] = @api_client.select_header_content_type(['application/json'])
+
+      # form parameters
+      form_params = opts[:form_params] || {}
+
+      # http body (model)
+      post_body = opts[:debug_body] || @api_client.object_to_http_body(body)
+
+      # return_type
+      return_type = opts[:debug_return_type]
+
+      # auth_names
+      auth_names = opts[:debug_auth_names] || [:apiKeyAuth, :appKeyAuth]
+
+      new_options = opts.merge(
+        :operation => :patch_dora_deployment_by_version,
+        :header_params => header_params,
+        :query_params => query_params,
+        :form_params => form_params,
+        :body => post_body,
+        :auth_names => auth_names,
+        :return_type => return_type,
+        :api_version => "V2"
+      )
+
+      data, status_code, headers = @api_client.call_api(Net::HTTP::Patch, local_var_path, new_options)
+      if @api_client.config.debugging
+        @api_client.config.logger.debug "API called: DORAMetricsAPI#patch_dora_deployment_by_version\nData: #{data.inspect}\nStatus code: #{status_code}\nHeaders: #{headers}"
+      end
+      return data, status_code, headers
+    end
   end
 end