tags

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

Overview

Name	tags
Type	Resource
Id	github.git.tags

Fields

The following fields are returned by SELECT queries:

get_tag

Response

Name	Datatype	Description
node_id	string	(example: MDM6VGFnOTQwYmQzMzYyNDhlZmFlMGY5ZWU1YmM3YjJkNWM5ODU4ODdiMTZhYw==)
message	string	Message describing the purpose of the tag (example: Initial public release)
object	object
sha	string	(example: 940bd336248efae0f9ee5bc7b2d5c985887b16ac)
tag	string	Name of the tag (example: v0.0.1)
tagger	object
url	string (uri)	URL for the tag (example: https://api.github.com/repositories/42/git/tags/940bd336248efae0f9ee5bc7b2d5c985887b16ac)
verification	object	(title: Verification)

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
get_tag	select	owner, repo, tag_sha		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 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_tag	insert	owner, repo, tag, message, object, type		Note that creating a tag object does not create the reference that makes a tag in Git. If you want to create an annotated tag in Git, you have to do this call to create the tag object, and then create the refs/tags/[tag] reference. If you want to create a lightweight tag, you only have to create the tag reference - this call would be unnecessary. 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 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
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.
tag_sha	string

SELECT examples

get_tag

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 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,
message,
object,
sha,
tag,
tagger,
url,
verification
FROM github.git.tags
WHERE owner = '{{ owner }}' -- required
AND repo = '{{ repo }}' -- required
AND tag_sha = '{{ tag_sha }}' -- required
;

INSERT examples

create_tag

Note that creating a tag object does not create the reference that makes a tag in Git. If you want to create an annotated tag in Git, you have to do this call to create the tag object, and then create the refs/tags/[tag] reference. If you want to create a lightweight tag, you only have to create the tag reference - this call would be unnecessary.

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 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.tags (
tag,
message,
object,
type,
tagger,
owner,
repo
)
SELECT 
'{{ tag }}' /* required */,
'{{ message }}' /* required */,
'{{ object }}' /* required */,
'{{ type }}' /* required */,
'{{ tagger }}',
'{{ owner }}',
'{{ repo }}'
RETURNING
node_id,
message,
object,
sha,
tag,
tagger,
url,
verification
;

Manifest

# Description fields are for documentation purposes
- name: tags
props:
  - name: owner
    value: "{{ owner }}"
    description: Required parameter for the tags resource.
  - name: repo
    value: "{{ repo }}"
    description: Required parameter for the tags resource.
  - name: tag
    value: "{{ tag }}"
    description: |
      The tag's name. This is typically a version (e.g., "v0.0.1").
  - name: message
    value: "{{ message }}"
    description: |
      The tag message.
  - name: object
    value: "{{ object }}"
    description: |
      The SHA of the git object this is tagging.
  - name: type
    value: "{{ type }}"
    description: |
      The type of the object we're tagging. Normally this is a `commit` but it can also be a `tree` or a `blob`.
    valid_values: ['commit', 'tree', 'blob']
  - name: tagger
    description: |
      An object with information about the individual creating the tag.
    value:
      name: "{{ name }}"
      email: "{{ email }}"
      date: "{{ date }}"