Reference documentation for GraphQL schema types in the Git category.

En este artículo

Mutations

createRef

Mutation

Create a new Git Ref.

Campos de entrada para createRef

Campos de retorno para createRef

NombreDescripción

clientMutationId (String)

A unique identifier for the client performing the mutation.

ref (Ref)

The newly created ref.

deleteRef

Mutation

Delete a Git Ref.

Campos de entrada para deleteRef

Campos de retorno para deleteRef

NombreDescripción

clientMutationId (String)

A unique identifier for the client performing the mutation.

updateRef

Mutation

Update a Git Ref.

Campos de entrada para updateRef

Campos de retorno para updateRef

NombreDescripción

clientMutationId (String)

A unique identifier for the client performing the mutation.

ref (Ref)

The updated Ref.

updateRefs

Mutation

Creates, updates and/or deletes multiple refs in a repository.

This mutation takes a list of RefUpdates and performs these updates on the repository. All updates are performed atomically, meaning that if one of them is rejected, no other ref will be modified.

RefUpdate.beforeOid specifies that the given reference needs to point to the given value before performing any updates. A value of 0000000000000000000000000000000000000000 can be used to verify that the references should not exist.

RefUpdate.afterOid specifies the value that the given reference will point to after performing all updates. A value of 0000000000000000000000000000000000000000 can be used to delete a reference.

If RefUpdate.force is set to true, a non-fast-forward updates for the given reference will be allowed.

Campos de entrada para updateRefs

Campos de retorno para updateRefs

NombreDescripción

clientMutationId (String)

A unique identifier for the client performing the mutation.

Objects

Blame

Object

Represents a Git blame.

Campos para Blame

NombreDescripción

ranges ([BlameRange!]!)

The list of ranges from a Git blame.

BlameRange

Object

Represents a range of information from a Git blame.

Campos para BlameRange

NombreDescripción

age (Int!)

Identifies the recency of the change, from 1 (new) to 10 (old). This is calculated as a 2-quantile and determines the length of distance between the median age of all the changes in the file and the recency of the current range's change.

commit (Commit!)

Identifies the line author.

endingLine (Int!)

The ending line for the range.

startingLine (Int!)

The starting line for the range.

Blob

Object

Represents a Git blob.

Blob Implementa

Campos para Blob

NombreDescripción

abbreviatedOid (String!)

An abbreviated version of the Git object ID.

byteSize (Int!)

Byte size of Blob object.

commitResourcePath (URI!)

The HTTP path for this Git object.

commitUrl (URI!)

The HTTP URL for this Git object.

id (ID!)

The Node ID of the Blob object.

isBinary (Boolean)

Indicates whether the Blob is binary or text. Returns null if unable to determine the encoding.

isTruncated (Boolean!)

Indicates whether the contents is truncated.

oid (GitObjectID!)

The Git object ID.

repository (Repository!)

The Repository the Git object belongs to.

text (String)

UTF8 text data or null if the Blob is binary.

GitActor

Object

Represents an actor in a Git commit (ie. an author or committer).

Campos para GitActor

NombreDescripción

avatarUrl (URI!)

A URL pointing to the author's public avatar.

Argumentos para avatarUrl

  • size (Int)

    The size of the resulting square image.

date (GitTimestamp)

The timestamp of the Git action (authoring or committing).

email (String)

The email in the Git commit.

name (String)

The name in the Git commit.

user (User)

The GitHub user corresponding to the email field. Null if no such user exists.

GitActorConnection

Object

The connection type for GitActor.

Campos para GitActorConnection

NombreDescripción

edges ([GitActorEdge])

A list of edges.

nodes ([GitActor])

A list of nodes.

pageInfo (PageInfo!)

Information to aid in pagination.

totalCount (Int!)

Identifies the total count of items in the connection.

GitActorEdge

Object

An edge in a connection.

Campos para GitActorEdge

NombreDescripción

cursor (String!)

A cursor for use in pagination.

node (GitActor)

The item at the end of the edge.

GpgSignature

Object

Represents a GPG signature on a Commit or Tag.

GpgSignature Implementa

Campos para GpgSignature

NombreDescripción

email (String!)

Email used to sign this object.

isValid (Boolean!)

True if the signature is valid and verified by GitHub.

keyId (String)

Hex-encoded ID of the key that signed this object.

payload (String!)

Payload for GPG signing object. Raw ODB object without the signature header.

signature (String!)

ASCII-armored signature header from object.

signer (User)

GitHub user corresponding to the email signing this commit.

state (GitSignatureState!)

The state of this signature. VALID if signature is valid and verified by GitHub, otherwise represents reason why signature is considered invalid.

verifiedAt (DateTime)

The date the signature was verified, if valid.

wasSignedByGitHub (Boolean!)

True if the signature was made with GitHub's signing key.

Push

Object

A Git push.

Push Implementa

Campos para Push

NombreDescripción

id (ID!)

The Node ID of the Push object.

nextSha (GitObjectID)

The SHA after the push.

permalink (URI!)

The permalink for this push.

previousSha (GitObjectID)

The SHA before the push.

pusher (Actor!)

The actor who pushed.

repository (Repository!)

The repository that was pushed to.

Ref

Object

Represents a Git reference.

Ref Implementa

Campos para Ref

NombreDescripción

associatedPullRequests (PullRequestConnection!)

A list of pull requests with this ref as the head ref.

Argumentos para associatedPullRequests

  • after (String)

    Returns the elements in the list that come after the specified cursor.

  • baseRefName (String)

    The base ref name to filter the pull requests by.

  • before (String)

    Returns the elements in the list that come before the specified cursor.

  • first (Int)

    Returns the first n elements from the list.

  • headRefName (String)

    The head ref name to filter the pull requests by.

  • labels ([String!])

    A list of label names to filter the pull requests by.

  • last (Int)

    Returns the last n elements from the list.

  • orderBy (IssueOrder)

    Ordering options for pull requests returned from the connection.

branchProtectionRule (BranchProtectionRule)

Branch protection rules for this ref.

compare (Comparison)

Compares the current ref as a base ref to another head ref, if the comparison can be made.

Argumentos para compare

  • headRef (String!)

    The head ref to compare against.

id (ID!)

The Node ID of the Ref object.

name (String!)

The ref name.

prefix (String!)

The ref's prefix, such as refs/heads/ or refs/tags/.

refUpdateRule (RefUpdateRule)

Branch protection rules that are viewable by non-admins.

repository (Repository!)

The repository the ref belongs to.

rules (RepositoryRuleConnection)

A list of rules from active Repository and Organization rulesets that apply to this ref.

Argumentos para rules

  • after (String)

    Returns the elements in the list that come after the specified cursor.

  • before (String)

    Returns the elements in the list that come before the specified cursor.

  • first (Int)

    Returns the first n elements from the list.

  • last (Int)

    Returns the last n elements from the list.

target (GitObject)

The object the ref points to. Returns null when object does not exist.

RefConnection

Object

The connection type for Ref.

Campos para RefConnection

NombreDescripción

edges ([RefEdge])

A list of edges.

nodes ([Ref])

A list of nodes.

pageInfo (PageInfo!)

Information to aid in pagination.

totalCount (Int!)

Identifies the total count of items in the connection.

RefEdge

Object

An edge in a connection.

Campos para RefEdge

NombreDescripción

cursor (String!)

A cursor for use in pagination.

node (Ref)

The item at the end of the edge.

RefUpdateRule

Object

Branch protection rules that are enforced on the viewer.

Campos para RefUpdateRule

NombreDescripción

allowsDeletions (Boolean!)

Can this branch be deleted.

allowsForcePushes (Boolean!)

Are force pushes allowed on this branch.

blocksCreations (Boolean!)

Can matching branches be created.

pattern (String!)

Identifies the protection rule pattern.

requiredApprovingReviewCount (Int)

Number of approving reviews required to update matching branches.

requiredStatusCheckContexts ([String])

List of required status check contexts that must pass for commits to be accepted to matching branches.

requiresCodeOwnerReviews (Boolean!)

Are reviews from code owners required to update matching branches.

requiresConversationResolution (Boolean!)

Are conversations required to be resolved before merging.

requiresLinearHistory (Boolean!)

Are merge commits prohibited from being pushed to this branch.

requiresSignatures (Boolean!)

Are commits required to be signed.

viewerAllowedToDismissReviews (Boolean!)

Is the viewer allowed to dismiss reviews.

viewerCanPush (Boolean!)

Can the viewer push to the branch.

SmimeSignature

Object

Represents an S/MIME signature on a Commit or Tag.

SmimeSignature Implementa

Campos para SmimeSignature

NombreDescripción

email (String!)

Email used to sign this object.

isValid (Boolean!)

True if the signature is valid and verified by GitHub.

payload (String!)

Payload for GPG signing object. Raw ODB object without the signature header.

signature (String!)

ASCII-armored signature header from object.

signer (User)

GitHub user corresponding to the email signing this commit.

state (GitSignatureState!)

The state of this signature. VALID if signature is valid and verified by GitHub, otherwise represents reason why signature is considered invalid.

verifiedAt (DateTime)

The date the signature was verified, if valid.

wasSignedByGitHub (Boolean!)

True if the signature was made with GitHub's signing key.

SshSignature

Object

Represents an SSH signature on a Commit or Tag.

SshSignature Implementa

Campos para SshSignature

NombreDescripción

email (String!)

Email used to sign this object.

isValid (Boolean!)

True if the signature is valid and verified by GitHub.

keyFingerprint (String)

Hex-encoded fingerprint of the key that signed this object.

payload (String!)

Payload for GPG signing object. Raw ODB object without the signature header.

signature (String!)

ASCII-armored signature header from object.

signer (User)

GitHub user corresponding to the email signing this commit.

state (GitSignatureState!)

The state of this signature. VALID if signature is valid and verified by GitHub, otherwise represents reason why signature is considered invalid.

verifiedAt (DateTime)

The date the signature was verified, if valid.

wasSignedByGitHub (Boolean!)

True if the signature was made with GitHub's signing key.

Submodule

Object

A pointer to a repository at a specific revision embedded inside another repository.

Campos para Submodule

NombreDescripción

branch (String)

The branch of the upstream submodule for tracking updates.

gitUrl (URI!)

The git URL of the submodule repository.

name (String!)

The name of the submodule in .gitmodules.

nameRaw (Base64String!)

The name of the submodule in .gitmodules (Base64-encoded).

path (String!)

The path in the superproject that this submodule is located in.

pathRaw (Base64String!)

The path in the superproject that this submodule is located in (Base64-encoded).

subprojectCommitOid (GitObjectID)

The commit revision of the subproject repository being tracked by the submodule.

SubmoduleConnection

Object

The connection type for Submodule.

Campos para SubmoduleConnection

NombreDescripción

edges ([SubmoduleEdge])

A list of edges.

nodes ([Submodule])

A list of nodes.

pageInfo (PageInfo!)

Information to aid in pagination.

totalCount (Int!)

Identifies the total count of items in the connection.

SubmoduleEdge

Object

An edge in a connection.

Campos para SubmoduleEdge

NombreDescripción

cursor (String!)

A cursor for use in pagination.

node (Submodule)

The item at the end of the edge.

Tag

Object

Represents a Git tag.

Tag Implementa

Campos para Tag

NombreDescripción

abbreviatedOid (String!)

An abbreviated version of the Git object ID.

commitResourcePath (URI!)

The HTTP path for this Git object.

commitUrl (URI!)

The HTTP URL for this Git object.

id (ID!)

The Node ID of the Tag object.

message (String)

The Git tag message.

name (String!)

The Git tag name.

oid (GitObjectID!)

The Git object ID.

repository (Repository!)

The Repository the Git object belongs to.

tagger (GitActor)

Details about the tag author.

target (GitObject!)

The Git object the tag points to.

Tree

Object

Represents a Git tree.

Tree Implementa

Campos para Tree

NombreDescripción

abbreviatedOid (String!)

An abbreviated version of the Git object ID.

commitResourcePath (URI!)

The HTTP path for this Git object.

commitUrl (URI!)

The HTTP URL for this Git object.

entries ([TreeEntry!])

A list of tree entries.

id (ID!)

The Node ID of the Tree object.

oid (GitObjectID!)

The Git object ID.

repository (Repository!)

The Repository the Git object belongs to.

TreeEntry

Object

Represents a Git tree entry.

Campos para TreeEntry

NombreDescripción

extension (String)

The extension of the file.

isGenerated (Boolean!)

Whether or not this tree entry is generated.

language (Language)

The programming language this file is written in.

lineCount (Int)

Number of lines in the file.

mode (Int!)

Entry file mode.

name (String!)

Entry file name.

nameRaw (Base64String!)

Entry file name. (Base64-encoded).

object (GitObject)

Entry file object.

oid (GitObjectID!)

Entry file Git object ID.

path (String)

The full path of the file.

pathRaw (Base64String)

The full path of the file. (Base64-encoded).

repository (Repository!)

The Repository the tree entry belongs to.

size (Int!)

Entry byte size.

submodule (Submodule)

If the TreeEntry is for a directory occupied by a submodule project, this returns the corresponding submodule.

type (String!)

Entry file type.

UnknownSignature

Object

Represents an unknown signature on a Commit or Tag.

UnknownSignature Implementa

Campos para UnknownSignature

NombreDescripción

email (String!)

Email used to sign this object.

isValid (Boolean!)

True if the signature is valid and verified by GitHub.

payload (String!)

Payload for GPG signing object. Raw ODB object without the signature header.

signature (String!)

ASCII-armored signature header from object.

signer (User)

GitHub user corresponding to the email signing this commit.

state (GitSignatureState!)

The state of this signature. VALID if signature is valid and verified by GitHub, otherwise represents reason why signature is considered invalid.

verifiedAt (DateTime)

The date the signature was verified, if valid.

wasSignedByGitHub (Boolean!)

True if the signature was made with GitHub's signing key.

Interfaces

GitObject

Interface

Represents a Git object.

GitObject se implementa mediante

Campos para GitObject

NombreDescripción

abbreviatedOid (String!)

An abbreviated version of the Git object ID.

commitResourcePath (URI!)

The HTTP path for this Git object.

commitUrl (URI!)

The HTTP URL for this Git object.

id (ID!)

The Node ID of the GitObject object.

oid (GitObjectID!)

The Git object ID.

repository (Repository!)

The Repository the Git object belongs to.

GitSignature

Interface

Information about a signature (GPG or S/MIME) on a Commit or Tag.

GitSignature se implementa mediante

Campos para GitSignature

NombreDescripción

email (String!)

Email used to sign this object.

isValid (Boolean!)

True if the signature is valid and verified by GitHub.

payload (String!)

Payload for GPG signing object. Raw ODB object without the signature header.

signature (String!)

ASCII-armored signature header from object.

signer (User)

GitHub user corresponding to the email signing this commit.

state (GitSignatureState!)

The state of this signature. VALID if signature is valid and verified by GitHub, otherwise represents reason why signature is considered invalid.

verifiedAt (DateTime)

The date the signature was verified, if valid.

wasSignedByGitHub (Boolean!)

True if the signature was made with GitHub's signing key.

Enums

GitSignatureState

Enum

The state of a Git signature.

Valores de GitSignatureState.

NombreDescripción
BAD_CERT

The signing certificate or its chain could not be verified.

BAD_EMAIL

Invalid email used for signing.

EXPIRED_KEY

Signing key expired.

GPGVERIFY_ERROR

Internal error - the GPG verification service misbehaved.

GPGVERIFY_UNAVAILABLE

Internal error - the GPG verification service is unavailable at the moment.

INVALID

Invalid signature.

MALFORMED_SIG

Malformed signature.

NOT_SIGNING_KEY

The usage flags for the key that signed this don't allow signing.

NO_USER

Email used for signing not known to GitHub.

OCSP_ERROR

Valid signature, though certificate revocation check failed.

OCSP_PENDING

Valid signature, pending certificate revocation checking.

OCSP_REVOKED

One or more certificates in chain has been revoked.

UNKNOWN_KEY

Key used for signing not known to GitHub.

UNKNOWN_SIG_TYPE

Unknown signature type.

UNSIGNED

Unsigned.

UNVERIFIED_EMAIL

Email used for signing unverified on GitHub.

VALID

Valid signature and verified by GitHub.

RefOrderField

Enum

Properties by which ref connections can be ordered.

Valores de RefOrderField.

NombreDescripción
ALPHABETICAL

Order refs by their alphanumeric name.

TAG_COMMIT_DATE

Order refs by underlying commit date if the ref prefix is refs/tags/.

Input objects

CommittableBranch

Input object

A git ref for a commit to be appended to.

The ref must be a branch, i.e. its fully qualified name must start with refs/heads/ (although the input is not required to be fully qualified).

The Ref may be specified by its global node ID or by the repositoryNameWithOwner and branchName.

Examples

Specify a branch using a global node ID:

{ "id": "MDM6UmVmMTpyZWZzL2hlYWRzL21haW4=" }

Specify a branch using repositoryNameWithOwner and branchName:

{
  "repositoryNameWithOwner": "github/graphql-client",
  "branchName": "main"
}.

Campos de entrada para CommittableBranch

NombreDescripción

branchName (String)

The unqualified name of the branch to append the commit to.

id (ID)

The Node ID of the Ref to be updated.

repositoryNameWithOwner (String)

The nameWithOwner of the repository to commit to.

CreateRefInput

Input object

Autogenerated input type of CreateRef.

Campos de entrada para CreateRefInput

NombreDescripción

clientMutationId (String)

A unique identifier for the client performing the mutation.

name (String!)

The fully qualified name of the new Ref (ie: refs/heads/my_new_branch).

oid (GitObjectID!)

The GitObjectID that the new Ref shall target. Must point to a commit.

repositoryId (ID!)

The Node ID of the Repository to create the Ref in.

DeleteRefInput

Input object

Autogenerated input type of DeleteRef.

Campos de entrada para DeleteRefInput

NombreDescripción

clientMutationId (String)

A unique identifier for the client performing the mutation.

refId (ID!)

The Node ID of the Ref to be deleted.

FileAddition

Input object

A command to add a file at the given path with the given contents as part of a commit. Any existing file at that that path will be replaced.

Campos de entrada para FileAddition

NombreDescripción

contents (Base64String!)

The base64 encoded contents of the file.

path (String!)

The path in the repository where the file will be located.

FileChanges

Input object

A description of a set of changes to a file tree to be made as part of a git commit, modeled as zero or more file additions and zero or more file deletions.

Both fields are optional; omitting both will produce a commit with no file changes.

deletions and additions describe changes to files identified by their path in the git tree using unix-style path separators, i.e. /. The root of a git tree is an empty string, so paths are not slash-prefixed.

path values must be unique across all additions and deletions provided. Any duplication will result in a validation error.

Encoding

File contents must be provided in full for each FileAddition.

The contents of a FileAddition must be encoded using RFC 4648 compliant base64, i.e. correct padding is required and no characters outside the standard alphabet may be used. Invalid base64 encoding will be rejected with a validation error.

The encoded contents may be binary.

For text files, no assumptions are made about the character encoding of the file contents (after base64 decoding). No charset transcoding or line-ending normalization will be performed; it is the client's responsibility to manage the character encoding of files they provide. However, for maximum compatibility we recommend using UTF-8 encoding and ensuring that all files in a repository use a consistent line-ending convention (\n or \r\n), and that all files end with a newline.

Modeling file changes

Each of the the five types of conceptual changes that can be made in a git commit can be described using the FileChanges type as follows:

  1. New file addition: create file hello world\n at path docs/README.txt:

    {
  "additions" [
    {
      "path": "docs/README.txt",
      "contents": base64encode("hello world\n")
    }
  ]
}

  2. Existing file modification: change existing docs/README.txt to have new content new content here\n:

    {
  "additions" [
    {
      "path": "docs/README.txt",
      "contents": base64encode("new content here\n")
    }
  ]
}

  3. Existing file deletion: remove existing file docs/README.txt. Note that the path is required to exist -- specifying a path that does not exist on the given branch will abort the commit and return an error.

    {
  "deletions" [
    {
      "path": "docs/README.txt"
    }
  ]
}

  4. File rename with no changes: rename docs/README.txt with previous content hello world\n to the same content at newdocs/README.txt:

    {
  "deletions" [
    {
      "path": "docs/README.txt",
    }
  ],
  "additions" [
    {
      "path": "newdocs/README.txt",
      "contents": base64encode("hello world\n")
    }
  ]
}

  5. File rename with changes: rename docs/README.txt with previous content hello world\n to a file at path newdocs/README.txt with content new contents\n:

    {
  "deletions" [
    {
      "path": "docs/README.txt",
    }
  ],
  "additions" [
    {
      "path": "newdocs/README.txt",
      "contents": base64encode("new contents\n")
    }
  ]
}.

Campos de entrada para FileChanges

NombreDescripción

additions ([FileAddition!])

File to add or change.

deletions ([FileDeletion!])

Files to delete.

FileDeletion

Input object

A command to delete the file at the given path as part of a commit.

Campos de entrada para FileDeletion

NombreDescripción

path (String!)

The path to delete.

RefOrder

Input object

Ways in which lists of git refs can be ordered upon return.

Campos de entrada para RefOrder

NombreDescripción

direction (OrderDirection!)

The direction in which to order refs by the specified field.

field (RefOrderField!)

The field in which to order refs by.

RefUpdate

Input object

A ref update.

Campos de entrada para RefUpdate

NombreDescripción

afterOid (GitObjectID!)

The value this ref should be updated to.

beforeOid (GitObjectID)

The value this ref needs to point to before the update.

force (Boolean)

Force a non fast-forward update.

name (GitRefname!)

The fully qualified name of the ref to be update. For example refs/heads/branch-name.

UpdateRefInput

Input object

Autogenerated input type of UpdateRef.

Campos de entrada para UpdateRefInput

NombreDescripción

clientMutationId (String)

A unique identifier for the client performing the mutation.

force (Boolean)

Permit updates of branch Refs that are not fast-forwards?.

oid (GitObjectID!)

The GitObjectID that the Ref shall be updated to target.

refId (ID!)

The Node ID of the Ref to be updated.

UpdateRefsInput

Input object

Autogenerated input type of UpdateRefs.

Campos de entrada para UpdateRefsInput

NombreDescripción

clientMutationId (String)

A unique identifier for the client performing the mutation.

refUpdates ([RefUpdate!]!)

A list of ref updates.

repositoryId (ID!)

The Node ID of the repository.