refs

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

Overview

Name	refs
Type	Resource
Id	github.git.refs

Fields

The following fields are returned by SELECT queries:

list_matching_refs

Response

Name	Datatype	Description
node_id	string
object	object
ref	string
url	string (uri)

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
list_matching_refs	select	owner, repo, ref		Returns an array of references from your Git database that match the supplied name. The :ref in the URL must be formatted as heads/<branch name> for branches and tags/<tag name> for tags. If the :ref doesn't exist in the repository, but existing refs start with :ref, they will be returned as an array. When you use this endpoint without providing a :ref, it will return an array of all the references from your Git database, including notes and stashes if they exist on the server. Anything in the namespace is returned, not just heads and tags. > [!NOTE] > You need to explicitly request a pull request to trigger a test merge commit, which checks the mergeability of pull requests. For more information, see "Checking mergeability of pull requests". If you request matching references for a branch named feature but the branch feature doesn't exist, the response can still include other matching head refs that start with the word feature, such as featureA and featureB.
create_ref	insert	owner, repo, ref, sha		Creates a reference for your repository. You are unable to create new references for empty repositories, even if the commit SHA-1 hash used exists. Empty repositories are repositories without branches.
update_ref	update	owner, repo, ref, sha		Updates the provided reference to point to a new SHA. For more information, see "Git References" in the Git documentation.
delete_ref	delete	owner, repo, ref		Deletes the provided reference.

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.
ref	string	The Git reference. For more information, see "Git References" in the Git documentation. (example: heads/feature-a)
repo	string	The name of the repository without the .git extension. The name is not case sensitive.

SELECT examples

list_matching_refs

Returns an array of references from your Git database that match the supplied name. The :ref in the URL must be formatted as heads/<branch name> for branches and tags/<tag name> for tags. If the :ref doesn't exist in the repository, but existing refs start with :ref, they will be returned as an array.

When you use this endpoint without providing a :ref, it will return an array of all the references from your Git database, including notes and stashes if they exist on the server. Anything in the namespace is returned, not just heads and tags.

> [!NOTE]
> You need to explicitly request a pull request to trigger a test merge commit, which checks the mergeability of pull requests. For more information, see "Checking mergeability of pull requests".

If you request matching references for a branch named feature but the branch feature doesn't exist, the response can still include other matching head refs that start with the word feature, such as featureA and featureB.

SELECT
node_id,
object,
ref,
url
FROM github.git.refs
WHERE owner = '{{ owner }}' -- required
AND repo = '{{ repo }}' -- required
AND ref = '{{ ref }}' -- required
;

INSERT examples

create_ref

Creates a reference for your repository. You are unable to create new references for empty repositories, even if the commit SHA-1 hash used exists. Empty repositories are repositories without branches.

INSERT INTO github.git.refs (
ref,
sha,
owner,
repo
)
SELECT 
'{{ ref }}' /* required */,
'{{ sha }}' /* required */,
'{{ owner }}',
'{{ repo }}'
RETURNING
node_id,
object,
ref,
url
;

Manifest

# Description fields are for documentation purposes
- name: refs
props:
  - name: owner
    value: "{{ owner }}"
    description: Required parameter for the refs resource.
  - name: repo
    value: "{{ repo }}"
    description: Required parameter for the refs resource.
  - name: ref
    value: "{{ ref }}"
    description: |
      The name of the fully qualified reference (ie: `refs/heads/master`). If it doesn't start with 'refs' and have at least two slashes, it will be rejected.
  - name: sha
    value: "{{ sha }}"
    description: |
      The SHA1 value for this reference.

UPDATE examples

update_ref

Updates the provided reference to point to a new SHA. For more information, see "Git References" in the Git documentation.

UPDATE github.git.refs
SET 
sha = '{{ sha }}',
force = {{ force }}
WHERE 
owner = '{{ owner }}' --required
AND repo = '{{ repo }}' --required
AND ref = '{{ ref }}' --required
AND sha = '{{ sha }}' --required
RETURNING
node_id,
object,
ref,
url;

DELETE examples

delete_ref

Deletes the provided reference.

DELETE FROM github.git.refs
WHERE owner = '{{ owner }}' --required
AND repo = '{{ repo }}' --required
AND ref = '{{ ref }}' --required
;