Change requests

Open, review, merge, and close change requests on a System. The walkthrough is Branching and change requests. Status values are ChangeRequestStatus: OPEN, MERGED, CLOSED.

All methods are on the Client. MERGED is produced only by merge_change_request(). update_change_request() accepts OPEN or CLOSED.

update_change_request is a full replacement of the mutable fields. Omitting title or description clears that field to null, so send the current values back when you are only changing the status.

Lifecycle

create_change_request()

Opens a change request from a source branch into a target branch.

• Parameters:

  • system_id (str) – System id. (required)
  • change_request_create_request (ChangeRequestCreateRequest) – (required). source_tag_id and target_tag_id are required. title and description are optional.
  • http_request_timeout_secs (int, optional) – Timeout for this request.

• Return Type: ChangeRequestResponseModel — call .actual_instance for the open change request (change_request_id, status, title, description).

get_change_request()

Returns one change request.

• Parameters:

  • system_id (str) – System id. (required)
  • change_request_id (str) – Change request id. (required)
  • http_request_timeout_secs (int, optional)

• Return Type: ChangeRequestResponseModel

list_change_requests()

Lists change requests on a System.

• Parameters:

  • system_id (str) – System id. (required)
  • status (ChangeRequestStatus, optional) – Filter by OPEN, MERGED, or CLOSED.
  • source_tag_id (str, optional) – Filter by source branch id.
  • target_tag_id (str, optional) – Filter by target branch id.
  • created_by_id (str, optional)
  • page (int, optional) – Page number, minimum 1.
  • size (int, optional) – Page size, 1–100. Default 10.
  • http_request_timeout_secs (int, optional)

• Return Type: PageChangeRequestResponseModel

update_change_request()

Replaces the mutable fields of a change request. Use status="CLOSED" to close an open request, and status="OPEN" to reopen a closed one. Setting status to the current value leaves the status unchanged. MERGED is rejected — merge with merge_change_request().

title and description are replaced by the values you send. Omit either one and that field is cleared.

• Parameters:

  • system_id (str) – System id. (required)
  • change_request_id (str) – Change request id. (required)
  • change_request_update_request (ChangeRequestUpdateRequest) – (required). status is required (OPEN or CLOSED). title, description, and comment are optional.
  • http_request_timeout_secs (int, optional)

• Return Type: ChangeRequestResponseModel

merge_change_request()

Merges an open change request into its target branch.

• Parameters:

  • system_id (str) – System id. (required)
  • change_request_id (str) – Change request id. (required)
  • change_request_merge_request (ChangeRequestMergeRequest) – (required). Optional comment.
  • check_only (bool, optional) – Run the staleness check and do not merge.
  • x_head_pair_token (str, optional) – head_pair_token from a prior change_request_changes() page.
  • http_request_timeout_secs (int, optional)

• Return Type: ChangeRequestResponseModel — .actual_instance.status is MERGED after a merge.

list_change_request_events()

Lists the event history of a change request. Event types are ChangeRequestEventType: OPENED, REOPENED, MERGED, CLOSED.

• Parameters:

  • system_id (str) – System id. (required)
  • change_request_id (str) – Change request id. (required)
  • page (int, optional)
  • size (int, optional) – 1–100. Default 10.
  • http_request_timeout_secs (int, optional)

• Return Type: PageChangeRequestEvent

Diff

change_request_change_summary()

Returns row counts for the diff between the change request's two branch heads: added_count, removed_count, and changed_count, summed across resources and subsystems.

• Parameters:

  • system_id (str) – System id. (required)
  • change_request_id (str) – Change request id. (required)
  • http_request_timeout_secs (int, optional)

• Return Type: ChangeRequestSummary

change_request_changes()

Returns one page of the diff. Each item's .actual_instance is a resource diff or a subsystem diff.

The page includes next_cursor, has_more, and head_pair_token. The token pins the source and target snapshots this page was computed from. Pass it back as x_head_pair_token on the next page, and pass next_cursor as cursor.

• Parameters:

  • system_id (str) – System id. (required)
  • change_request_id (str) – Change request id. (required)
  • component_type (ChangeRequestComponentType, optional) – RESOURCE, SUBSYSTEM, or ALL.
  • change_types (list of ChangeRequestDiffType, optional) – ADDED, REMOVED, CHANGED.
  • search (str, optional) – Name filter.
  • cursor (str, optional) – next_cursor from the previous page.
  • limit (int, optional) – Page size, maximum 100.
  • allow_head_refresh (bool, optional)
  • x_head_pair_token (str, optional) – head_pair_token from the previous page.
  • http_request_timeout_secs (int, optional)

• Return Type: ChangeRequestDiffPage

Comparing two snapshots, or a branch head against live tracked state, uses compare_snapshots() and compare_tag_to_live(). Those calls share the same component and change-type filters.