commits

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

Overview

Name	commits
Type	Resource
Id	github.git.commits

Fields

The following fields are returned by SELECT queries:

get_commit

Response

Name	Datatype	Description
node_id	string
author	object	Identifying information for the git-user
committer	object	Identifying information for the git-user
html_url	string (uri)
message	string	Message describing the purpose of the commit (example: Fix #42)
parents	array
sha	string	SHA for the commit (example: 7638417db6d59f3c431d3e1f261cc637155684cd)
tree	object
url	string (uri)
verification	object

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
get_commit	select	owner, repo, commit_sha		Gets a Git commit object. To get the contents of a commit, see "Get a commit." Signature verification object The response will include a verification object that describes the result of verifying the commit's signature. The following fields are included in the verification object: | Name | Type | Description | | ---- | ---- | ----------- | | verified | boolean | Indicates whether GitHub considers the signature in this commit to be verified. | | reason | string | The reason for verified value. Possible values and their meanings are enumerated in the table below. | | signature | string | The signature that was extracted from the commit. | | payload | string | The value that was signed. | | verified_at | string | The date the signature was verified by GitHub. | These are the possible values for reason in the verification object: | Value | Description | | ----- | ----------- | | expired_key | The key that made the signature is expired. | | not_signing_key | The "signing" flag is not among the usage flags in the GPG key that made the signature. | | gpgverify_error | There was an error communicating with the signature verification service. | | gpgverify_unavailable | The signature verification service is currently unavailable. | | unsigned | The object does not include a signature. | | unknown_signature_type | A non-PGP signature was found in the commit. | | no_user | No user was associated with the committer email address in the commit. | | unverified_email | The committer email address in the commit was associated with a user, but the email address is not verified on their account. | | bad_email | The committer email address in the commit is not included in the identities of the PGP key that made the signature. | | unknown_key | The key that made the signature has not been registered with any user's account. | | malformed_signature | There was an error parsing the signature. | | invalid | The signature could not be cryptographically verified using the key whose key-id was found in the signature. | | valid | None of the above errors applied, so the signature is considered to be verified. |
create_commit	insert	owner, repo, message, tree		Creates a new Git commit object. Signature verification object The response will include a verification object that describes the result of verifying the commit's signature. The following fields are included in the verification object: | Name | Type | Description | | ---- | ---- | ----------- | | verified | boolean | Indicates whether GitHub considers the signature in this commit to be verified. | | reason | string | The reason for verified value. Possible values and their meanings are enumerated in the table below. | | signature | string | The signature that was extracted from the commit. | | payload | string | The value that was signed. | | verified_at | string | The date the signature was verified by GitHub. | These are the possible values for reason in the verification object: | Value | Description | | ----- | ----------- | | expired_key | The key that made the signature is expired. | | not_signing_key | The "signing" flag is not among the usage flags in the GPG key that made the signature. | | gpgverify_error | There was an error communicating with the signature verification service. | | gpgverify_unavailable | The signature verification service is currently unavailable. | | unsigned | The object does not include a signature. | | unknown_signature_type | A non-PGP signature was found in the commit. | | no_user | No user was associated with the committer email address in the commit. | | unverified_email | The committer email address in the commit was associated with a user, but the email address is not verified on their account. | | bad_email | The committer email address in the commit is not included in the identities of the PGP key that made the signature. | | unknown_key | The key that made the signature has not been registered with any user's account. | | malformed_signature | There was an error parsing the signature. | | invalid | The signature could not be cryptographically verified using the key whose key-id was found in the signature. | | valid | None of the above errors applied, so the signature is considered to be verified. |

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
commit_sha	string	The SHA of the commit.
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.

SELECT examples

get_commit

Gets a Git commit object.

To get the contents of a commit, see "Get a commit."

Signature verification object

The response will include a verification object that describes the result of verifying the commit's signature. The following fields are included in the verification object:

| Name | Type | Description |
| ---- | ---- | ----------- |
| verified | boolean | Indicates whether GitHub considers the signature in this commit to be verified. |
| reason | string | The reason for verified value. Possible values and their meanings are enumerated in the table below. |
| signature | string | The signature that was extracted from the commit. |
| payload | string | The value that was signed. |
| verified_at | string | The date the signature was verified by GitHub. |

These are the possible values for reason in the verification object:

| Value | Description |
| ----- | ----------- |
| expired_key | The key that made the signature is expired. |
| not_signing_key | The "signing" flag is not among the usage flags in the GPG key that made the signature. |
| gpgverify_error | There was an error communicating with the signature verification service. |
| gpgverify_unavailable | The signature verification service is currently unavailable. |
| unsigned | The object does not include a signature. |
| unknown_signature_type | A non-PGP signature was found in the commit. |
| no_user | No user was associated with the committer email address in the commit. |
| unverified_email | The committer email address in the commit was associated with a user, but the email address is not verified on their account. |
| bad_email | The committer email address in the commit is not included in the identities of the PGP key that made the signature. |
| unknown_key | The key that made the signature has not been registered with any user's account. |
| malformed_signature | There was an error parsing the signature. |
| invalid | The signature could not be cryptographically verified using the key whose key-id was found in the signature. |
| valid | None of the above errors applied, so the signature is considered to be verified. |

SELECT
node_id,
author,
committer,
html_url,
message,
parents,
sha,
tree,
url,
verification
FROM github.git.commits
WHERE owner = '{{ owner }}' -- required
AND repo = '{{ repo }}' -- required
AND commit_sha = '{{ commit_sha }}' -- required
;

INSERT examples

create_commit

Creates a new Git commit object.

Signature verification object

The response will include a verification object that describes the result of verifying the commit's signature. The following fields are included in the verification object:

| Name | Type | Description |
| ---- | ---- | ----------- |
| verified | boolean | Indicates whether GitHub considers the signature in this commit to be verified. |
| reason | string | The reason for verified value. Possible values and their meanings are enumerated in the table below. |
| signature | string | The signature that was extracted from the commit. |
| payload | string | The value that was signed. |
| verified_at | string | The date the signature was verified by GitHub. |

These are the possible values for reason in the verification object:

| Value | Description |
| ----- | ----------- |
| expired_key | The key that made the signature is expired. |
| not_signing_key | The "signing" flag is not among the usage flags in the GPG key that made the signature. |
| gpgverify_error | There was an error communicating with the signature verification service. |
| gpgverify_unavailable | The signature verification service is currently unavailable. |
| unsigned | The object does not include a signature. |
| unknown_signature_type | A non-PGP signature was found in the commit. |
| no_user | No user was associated with the committer email address in the commit. |
| unverified_email | The committer email address in the commit was associated with a user, but the email address is not verified on their account. |
| bad_email | The committer email address in the commit is not included in the identities of the PGP key that made the signature. |
| unknown_key | The key that made the signature has not been registered with any user's account. |
| malformed_signature | There was an error parsing the signature. |
| invalid | The signature could not be cryptographically verified using the key whose key-id was found in the signature. |
| valid | None of the above errors applied, so the signature is considered to be verified. |

INSERT INTO github.git.commits (
message,
tree,
parents,
author,
committer,
signature,
owner,
repo
)
SELECT 
'{{ message }}' /* required */,
'{{ tree }}' /* required */,
'{{ parents }}',
'{{ author }}',
'{{ committer }}',
'{{ signature }}',
'{{ owner }}',
'{{ repo }}'
RETURNING
node_id,
author,
committer,
html_url,
message,
parents,
sha,
tree,
url,
verification
;

Manifest

# Description fields are for documentation purposes
- name: commits
props:
  - name: owner
    value: "{{ owner }}"
    description: Required parameter for the commits resource.
  - name: repo
    value: "{{ repo }}"
    description: Required parameter for the commits resource.
  - name: message
    value: "{{ message }}"
    description: |
      The commit message
  - name: tree
    value: "{{ tree }}"
    description: |
      The SHA of the tree object this commit points to
  - name: parents
    value:
      - "{{ parents }}"
    description: |
      The full SHAs of the commits that were the parents of this commit. If omitted or empty, the commit will be written as a root commit. For a single parent, an array of one SHA should be provided; for a merge commit, an array of more than one should be provided.
  - name: author
    description: |
      Information about the author of the commit. By default, the `author` will be the authenticated user and the current date. See the `author` and `committer` object below for details.
    value:
      name: "{{ name }}"
      email: "{{ email }}"
      date: "{{ date }}"
  - name: committer
    description: |
      Information about the person who is making the commit. By default, `committer` will use the information set in `author`. See the `author` and `committer` object below for details.
    value:
      name: "{{ name }}"
      email: "{{ email }}"
      date: "{{ date }}"
  - name: signature
    value: "{{ signature }}"
    description: |
      The [PGP signature](https://en.wikipedia.org/wiki/Pretty_Good_Privacy) of the commit. GitHub adds the signature to the `gpgsig` header of the created commit. For a commit signature to be verifiable by Git or GitHub, it must be an ASCII-armored detached PGP signature over the string commit as it would be written to the object database. To pass a `signature` parameter, you need to first manually create a valid PGP signature, which can be complicated. You may find it easier to [use the command line](https://git-scm.com/book/id/v2/Git-Tools-Signing-Your-Work) to create signed commits.