The GitHub generator allows you to automatically fetch the latest releate/tag/commit of your project from GitHub using the GitHub API.

Its input struct looks like this:

{
    "name": "pkgname",
    "github":
    {
        "user": "user",
        "repo": "repository",
        "query": "releases",

        "select": "^\\\\d+\\\\.\\\\d+\\\\.\\\\d+$",
        "transforms": 
        [
            [ "v", "" ]
        ],
        "version": "v1.0.0.0",

        "artifacts": 
        [
            "pkgname-{version}.tar.xz",
            "resources.tar.xz"
        ],
        "include-drafts": "false",
        "include-pre-releases": "true",

        "domain": "github.com",
        "api-domain": "api.github.com" 
    }
}

Note

Note that this is a showcase of all the possible keys, some keys may cause conflicts when both declared. Others only work for specific query types

There are 3 mandatory fields for the GitHub generator to work:

  1. user - a valid GitHub username
  2. repo - a valid GitHub repository
  3. query - a valid query string. One of either releases, tags or commits

The following 2 fields are for users of GitHub Enterprise that host their own GitHub instance under their own domain:

  1. domain - A custom domain for a GitHub Enterprise instance. When not set, defaults to github.com
  2. api-domain - A custom API domain for a GitHub Enterprise instance. When not set, defaults to api.github.com. Most enterprise instances usually put their GitHub API URL as myorgsgithub.tld/api

All other fields will be defined in the following sections.

Commit queries

When setting the query field to commits, the generator tries to:

  1. If an additional version field is declared containing a commit SHA - tries to find a commit with that SHA and if it finds it, it uses that commit's source archive as the source tarball
  2. If there is no additonal version field, it simply uses the latest commit's archive source tarball

Commit versions cannot be controled by the user. Instead we use the commit's commiter date in the YYYYMMDD date format.

Tag queries

When setting the query field to tags, the generator tries to do the following:

  1. Selecting the tag:
    • It checks if the optional select field is defined. If it is, the regex string is used as a filter for the list of tags. This field cannot be used along with version
    • If there is no select field but there is the optional version field, it tries to find that specific version and use its source tarball
    • If there is no select field and there is no version field it selects the latest tag
  2. Transforming the tag(optional):
    • The transforms field is an optional field that allows for you to write regex replace sequences for transforming versions with unorthodox formats into a format that packaging systems accept. It is an array of pairs(JSON arrays with 2 members) where the first member of the pair is the search string and the second is the replace string. Each pair is applied sequentially.
    • Replacements are applied for any version, regardless of whether it was fetched with the version key

Release queries

Release queries follow the same steps as tag queries, except for the following:

  1. Releases can be drafts or pre-releases. By default, we only use regular releases, however, we allow for you to disable this filtering by setting the include-drafts and include-pre-releases fields to true respectively.
  2. GitHub releases support attaching additional artifacts to them. These artifacts can be downloaded by adding their names in the optional artifacts array. Each name can be templated using the {parameter} syntax, where we accept the following parameters:
    • version
    • pkgname
    • github_user
    • github_repo

Note

If the artifacts array is defined, the source code tarball archive URL will still be the first URL in the tarball-urls list. Additional artifacts will be appended after it.

Generator exports

The GitHub generator also exports the following variables:

  1. description - The GitHub repository's description if defined
  2. license - The GitHub repository's license if defined
  3. homepage - The GitHub repository's homepage if defined

These variables will only take precedent if not defined previously in the metadata file.