MergeQueue
MergeQueue
A merge job is the server-side task that the merge method of the Branch class starts. The MergeQueue class reads merge jobs through the Content Management API (CMA). Use this class to
- list the recent merge jobs of a stack
- check the status and configuration of one merge job, for example after you start a merge
Call the mergeQueue method on stack.branch() to get an object.
Instance State
- Call stack.branch().mergeQueue() without a UID to list merge jobs with find.
- Call stack.branch().mergeQueue('<MERGE_JOB_UID>') to read one merge job with fetch.
- Each form has only its own request method. fetch is undefined on mergeQueue(), and find is undefined on mergeQueue('<MERGE_JOB_UID>'), so calling the wrong one throws TypeError.
Warning mergeQueue('') returns the list form, because the SDK treats an empty string as no UID. Check the UID before you build the object.
Class-Level Notes
Results.
Headers.
- Known issue: In 1.32.0, the merge queue requests ignore headers that you change on the MergeQueue object with addHeader, addHeaderDict or removeHeader. Change the header on the branch object before you call mergeQueue, for example stack.branch().addHeader('x-request-id', 'docs-123').mergeQueue().
- Every request sends the headers that the branch object held when you called mergeQueue.
Rate limiting and retry.
- This SDK automatically retries on 429 with configurable delay and attempt limits.
Additional Resource For more information on the retry options and their defaults, refer to the Contentstack documentation.
Method Index
List merge jobs. Available on stack.branch().mergeQueue().
| Method Name | Returns | Description |
|---|---|---|
| find | The recent merge jobs of the stack. | Lists recent merge jobs. |
Read one merge job. Available on stack.branch().mergeQueue('<MERGE_JOB_UID>').
| Method Name | Returns | Description |
|---|---|---|
| fetch | The status and configuration of the merge job. | Reads one merge job. |
Set request headers. Available on both forms.
| Method Name | Returns | Description |
|---|---|---|
| addHeader | The same merge queue object, for chaining. | Adds one request header. |
| addHeaderDict | The same merge queue object, for chaining. | Adds several request headers. |
| removeHeader | The same merge queue object, for chaining. | Removes one request header. |
Class-Level Snippet
The snippet below starts a merge into main and then lists the recent merge jobs of the stack.
import contentstack from '@contentstack/management'
const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })
try {
await stack.branch().merge({}, {
base_branch: 'main',
compare_branch: '<COMPARE_BRANCH>',
default_merge_strategy: 'merge_prefer_base',
merge_comment: 'Merge the redesign into main'
})
const jobs = await stack.branch().mergeQueue().find()
console.log(JSON.stringify(jobs))
} catch (error) {
// The API rejected the request. The error carries status, errorCode, errorMessage and errors.
console.error(error.status, error.errorCode, error.errorMessage)
}Methods
Each method of the MergeQueue class has its own section below, with its parameters, validation rules, behavior, and examples.
addHeader
addHeader adds one header to the requests that this merge queue object sends.
| Name | Type | Description |
|---|---|---|
| key (required) | string | Header name, for example x-request-id. |
| value (required) | string | Header value to send. |
Returns: MergeQueue. The same merge queue object, for chaining.
- Known issue: In 1.32.0, the merge queue requests ignore headers that you change on the MergeQueue object. Add, change or remove the header on the branch object before you call mergeQueue, for example stack.branch().addHeader('x-request-id', 'docs-123').mergeQueue().
Validation
- There is no client-side validation. A null or undefined key leaves the headers unchanged, and addHeader returns the same object.
- An invalid value surfaces as a rejected promise from the request method you call next.
Behavior
- Client-side only. addHeader sends no request.
- The first header change on this object copies the headers that it inherited. The change then applies to this object only, not to the stack or to other objects that the same stack creates.
- The header map of this object changes, but the request methods of this object do not read it. See the known issue above.
- A key that the object already holds gets the new value.
Example
Basic usage: tag the requests of one merge queue object
import contentstack from '@contentstack/management'
const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })
const target = stack.branch().mergeQueue().addHeader('x-request-id', 'docs-123')
console.log(target.stackHeaders['x-request-id'])addHeaderDict
addHeaderDict adds several headers at once to the requests that this merge queue object sends.
| Name | Type | Description |
|---|---|---|
| headerDict (required) | object | Header names and values to add. |
Returns: MergeQueue. The same merge queue object, for chaining.
- Known issue: In 1.32.0, the merge queue requests ignore headers that you change on the MergeQueue object. Add, change or remove the header on the branch object before you call mergeQueue, for example stack.branch().addHeader('x-request-id', 'docs-123').mergeQueue().
Validation
- There is no client-side validation. A null value, or a value that is not an object, leaves the headers unchanged, and addHeaderDict returns the same object.
- An invalid value surfaces as a rejected promise from the request method you call next.
Behavior
- Client-side only. addHeaderDict sends no request.
- addHeaderDict copies every key of headerDict into the header map of this object. A key that the object already holds gets the new value.
- The first header change on this object copies the headers that it inherited. The change then applies to this object only, not to the stack or to other objects that the same stack creates.
- The header map of this object changes, but the request methods of this object do not read it. See the known issue above.
Example
Basic usage: add a request ID and a trace ID
import contentstack from '@contentstack/management'
const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })
const target = stack.branch().mergeQueue().addHeaderDict({ 'x-request-id': 'docs-123', 'x-trace-id': 'trace-456' })
console.log(target.stackHeaders['x-request-id'], target.stackHeaders['x-trace-id'])fetch
fetch retrieves the status and configuration of the merge job whose UID you passed to mergeQueue('<MERGE_JOB_UID>').
This method takes no parameters.
Returns: Promise<Response>. The status and configuration of the merge job.
Validation
- There is no client-side validation.
- fetch exists only on stack.branch().mergeQueue('<MERGE_JOB_UID>'). On mergeQueue() it is undefined, and calling it throws TypeError.
- The returned promise rejects with an Error when the API rejects the request. The error carries status, statusText, errorMessage, errorCode and errors from the API response.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- Sends GET /v3/stacks/branches_queue/{merge_job_uid} with no query parameters, as Get single merge job describes.
- Resolves to the response body as a plain object.
- Call fetch again later to check the progress of a merge that the merge method started.
Example
Basic usage: check one merge job
import contentstack from '@contentstack/management'
const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })
try {
const job = await stack.branch().mergeQueue('<MERGE_JOB_UID>').fetch()
console.log(JSON.stringify(job))
} catch (error) {
// The API rejected the request. The error carries status, errorCode, errorMessage and errors.
console.error(error.status, error.errorCode, error.errorMessage)
}find
find lists the recent merge jobs of the stack.
| Name | Type | Description |
|---|---|---|
| params | object | Query parameters, sent as given. |
Returns: Promise<Response>. The recent merge jobs of the stack.
Validation
- There is no client-side validation.
- find exists only on stack.branch().mergeQueue(). On mergeQueue('<MERGE_JOB_UID>') it is undefined, and calling it throws TypeError.
- The returned promise rejects with an Error when the API rejects the request. The error carries status, statusText, errorMessage, errorCode and errors from the API response.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- Sends GET /v3/stacks/branches_queue with every key of params as a query parameter, as Get all merge jobs describes. The API reference lists no query parameters for this request.
- The API returns the last 100 merge jobs by default.
- Resolves to the response body as a plain object.
- To read one job, pass its UID to the mergeQueue method and call fetch.
Example
Basic usage: list the recent merge jobs
import contentstack from '@contentstack/management'
const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })
try {
const jobs = await stack.branch().mergeQueue().find()
console.log(JSON.stringify(jobs))
} catch (error) {
// The API rejected the request. The error carries status, errorCode, errorMessage and errors.
console.error(error.status, error.errorCode, error.errorMessage)
}All parameters: pass query parameters
import contentstack from '@contentstack/management'
const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })
try {
// find sends every key of the object as a query parameter. The API lists none for this request.
const jobs = await stack.branch().mergeQueue().find({})
console.log(JSON.stringify(jobs))
} catch (error) {
console.error(error.errorMessage)
}removeHeader
removeHeader removes one header from the requests that this merge queue object sends.
| Name | Type | Description |
|---|---|---|
| key (required) | string | Name of the header to remove. |
Returns: MergeQueue. The same merge queue object, for chaining.
- Known issue: In 1.32.0, the merge queue requests ignore headers that you change on the MergeQueue object. Add, change or remove the header on the branch object before you call mergeQueue, for example stack.branch().addHeader('x-request-id', 'docs-123').mergeQueue().
Validation
- There is no client-side validation. A null or undefined key, or a key that the object does not hold, leaves the headers unchanged, and removeHeader returns the same object.
- An invalid value surfaces as a rejected promise from the request method you call next.
Behavior
- Client-side only. removeHeader sends no request.
- The first header change on this object copies the headers that it inherited. The change then applies to this object only, not to the stack or to other objects that the same stack creates.
- The header map of this object changes, but the request methods of this object do not read it. See the known issue above.
- removeHeader can remove a header that the object inherited from the stack, such as branch. The stack and its other objects keep that header.
- Without api_key, the API cannot tell which stack the request is for. Do not remove it.
Example
Basic usage: drop a header that you added earlier
import contentstack from '@contentstack/management'
const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })
const target = stack.branch().mergeQueue()
.addHeaderDict({ 'x-request-id': 'docs-123', 'x-trace-id': 'trace-456' })
.removeHeader('x-trace-id')
console.log('x-trace-id' in target.stackHeaders) // false