# Github Release<no value>
// <!-- Required for asciidoctor -->
:toc:
// Set toclevels to be at least your hugo [markup.tableOfContents.endLevel] config key
:toclevels: 4

[cols="1^,1^,1^",options=header]
|===
| source | condition | target
| &#10004; | &#10004; | &#10007;
|===

== Description

The `githubrelease` resource reads the releases published on a GitHub repository.

**source**::
Returns the latest release, sorted by release date.

**condition**::
Checks that `tag` corresponds to a published release.

**target**::
Not supported - a target fails with `target not supported for the plugin GitHub Release`. Updatecli does not publish releases; to create a tag, use link:/docs/plugins/resource/gitTag/[`gittag`].

NOTE: An `scm` attached to a condition is ignored, with the warning `condition not supported for plugin GitHub Release used with scm`.

=== Releases and tags are not the same list

When a repository has no releases, Updatecli falls back to its **tags**, sorted by tag creation date.

The two lists are mutually exclusive: a repository that publishes releases is read through the release list only, so a tag without a matching release is invisible. This is the usual explanation for a version that exists on GitHub but that a source will not return.

== Parameters

{{< resourceparameters "sources" "githubrelease" >}}

`owner` and `repository` are mandatory. `tag` is condition-only.

=== key

`key` chooses what the source returns:

[cols="1,3",options=header]
|===
| Value | Returns
| `tagname` | The tag name. The default.
| `taghash` | The commit hash the tag points at.
| `title` | The release title.
|===

`name` and `hash` are deprecated aliases for `tagname` and `taghash`; they still work and log a warning. Anything else is a validation error listing the accepted values.

=== typefilter

`typefilter` selects which kinds of release count. Its default is the important part:

[source,yaml]
----
spec:
  typefilter:
    draft: false
    prerelease: false
    release: true
    latest: false
----

**When `draft`, `prerelease` and `release` are all left unset, `release` is turned on** - so out of the box only stable releases are considered, and pre-releases are ignored. Set `prerelease: true` to include them.

`latest: true` narrows the result to the single release GitHub itself flags as "Latest", which is not necessarily the most recent one by date.

=== Authentication

include::content/en/docs/plugins/_githubAuth.adoc[]

`app` configures GitHub App authentication and is **not compatible with `token` and `username`**. It is the better option where it is available: scoped permissions and short-lived credentials.

IMPORTANT: Storing credentials in an unencrypted file is a bad practice. Read the token from an environment variable with `'{{ requiredEnv "GITHUB_TOKEN" }}'`.

=== Version Filter

include::content/en/docs/plugins/_versionFilter.adoc[]

[source,yaml]
----
# source.yaml
{{<include "assets/code_example/docs/plugins/resources/github/release/updatecli.d/source.yaml">}}
----

=> Returns v1.10.3

== Example

[source,yaml]
----
# updatecli.yaml
{{<include "assets/code_example/docs/plugins/resources/github/release/updatecli.d/updatecli.yaml">}}
----

== Links

* link:/docs/plugins/scm/github/[The `github` scm] - to clone and push
* link:/docs/plugins/actions/github/[The `github/pullrequest` action]
* link:/docs/core/versionfilter/["Version Filtering" page]