stacks

Creates, updates, deletes, gets or lists a stacks resource.

Overview

Name	stacks
Type	Resource
Id	github.pulls.stacks

Fields

The following fields are returned by SELECT queries:

get

Response

Name	Datatype	Description
id	integer
node_id	string
base	object
created_at	string (date-time)
number	integer
open	boolean	Whether the stack has any open pull request. False when all pull requests are merged or closed.
pull_requests	array
url	string (uri)

list

Response

Name	Datatype	Description
id	integer
node_id	string
base	object
created_at	string (date-time)
number	integer
open	boolean	Whether the stack has any open pull request. False when all pull requests are merged or closed.
pull_requests	array
url	string (uri)

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
get	select	owner, repo, stack_number		Gets a pull request stack by providing its stack number.
list	select	owner, repo	pull_request, per_page, page	Lists pull request stacks in a repository.
create	insert	owner, repo, pull_requests		Creates a stack from an ordered list of pull request numbers. Provide the pull request numbers from the bottom of the stack to the top. Each pull request's base ref must match the previous pull request's head ref.
add	exec	owner, repo, stack_number, pull_requests		Appends an ordered list of pull request numbers onto the top of an existing stack. Provide only the pull requests you want to add, from the current top of the stack upward. The first new pull request's base ref must match the current top pull request's head ref.
unstack	exec	owner, repo, stack_number		Removes the unmerged pull requests from a stack. Pull requests that cannot be unstacked (for example, those that are queued for merge) are left in place. When pull requests remain in the stack, the updated stack is returned with a 200. When no pull requests remain, the stack is dissolved and a 204 is returned.

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
owner	string	The account owner of the repository. The name is not case sensitive.
repo	string	The name of the repository without the .git extension. The name is not case sensitive.
stack_number	integer	The number that identifies the pull request stack.
page	integer	The page number of the results to fetch. For more information, see "Using pagination in the REST API."
per_page	integer	The number of results per page (max 100). For more information, see "Using pagination in the REST API."
pull_request	integer	Filter to the stack containing this repository pull request number.

SELECT examples

get

Gets a pull request stack by providing its stack number.

SELECT
id,
node_id,
base,
created_at,
number,
open,
pull_requests,
url
FROM github.pulls.stacks
WHERE owner = '{{ owner }}' -- required
AND repo = '{{ repo }}' -- required
AND stack_number = '{{ stack_number }}' -- required
;

list

Lists pull request stacks in a repository.

SELECT
id,
node_id,
base,
created_at,
number,
open,
pull_requests,
url
FROM github.pulls.stacks
WHERE owner = '{{ owner }}' -- required
AND repo = '{{ repo }}' -- required
AND pull_request = '{{ pull_request }}'
AND per_page = '{{ per_page }}'
AND page = '{{ page }}'
;

INSERT examples

create

Creates a stack from an ordered list of pull request numbers. Provide the pull
request numbers from the bottom of the stack to the top. Each pull request's
base ref must match the previous pull request's head ref.

INSERT INTO github.pulls.stacks (
pull_requests,
owner,
repo
)
SELECT 
'{{ pull_requests }}' /* required */,
'{{ owner }}',
'{{ repo }}'
RETURNING
id,
node_id,
base,
created_at,
number,
open,
pull_requests,
url
;

Manifest

# Description fields are for documentation purposes
- name: stacks
props:
  - name: owner
    value: "{{ owner }}"
    description: Required parameter for the stacks resource.
  - name: repo
    value: "{{ repo }}"
    description: Required parameter for the stacks resource.
  - name: pull_requests
    value:
      - {{ pull_requests }}
    description: |
      An ordered list of pull request numbers forming the stack from bottom to top.

Lifecycle Methods

add

Appends an ordered list of pull request numbers onto the top of an existing
stack. Provide only the pull requests you want to add, from the current top of
the stack upward. The first new pull request's base ref must match the current
top pull request's head ref.

EXEC github.pulls.stacks.add 
@owner='{{ owner }}' --required, 
@repo='{{ repo }}' --required, 
@stack_number='{{ stack_number }}' --required 
@@json=
'{
"pull_requests": "{{ pull_requests }}"
}'
;

unstack

Removes the unmerged pull requests from a stack. Pull requests that cannot be
unstacked (for example, those that are queued for merge) are left in place. When pull requests remain in the stack, the updated
stack is returned with a 200. When no pull requests remain, the stack is
dissolved and a 204 is returned.

EXEC github.pulls.stacks.unstack 
@owner='{{ owner }}' --required, 
@repo='{{ repo }}' --required, 
@stack_number='{{ stack_number }}' --required
;