dodevops/githubreleases

Table of Contents

1. Description
2. Usage - Configuration options and additional functionality
3. Reference - An under-the-hood peek at what the module is doing and how
   1. Class githubreleases
   2. Type githubreleases::download

Description

This puppet module downloads tar-, zipballs or assets from Github releases.

Assets can be filtered by Content type and/or file name.

Usage

To download a release from Github, use the defined type githubreleases::download like this:

githubreleases::download {
  '/tmp/release.latest.head.tar.gz':
    author     => 'company',
    repository => 'example'
}

This will download the latest (HEAD) version of the project "company/example" as a tarball an place it in /tmp/release.latest.head.tar.gz.

If the repository uses the Github release feature, the tarball of the latest (non-pre-release) release will be downloaded.

If the repository uses assets to offer binary files with each release, these can also be downloaded:

githubreleases::download {
  '/tmp/release.0.0.2.asset.debian':
    author            => 'company',
    repository        => 'example',
    release           => '0.0.2',
    asset             => true,
    asset_contenttype => 'application\/x-deb'
}

This will download a debian package of release 0.0.2 of the repository.

File names can be filtered as well:

githubreleases::download {
  '/tmp/release.0.0.2.asset.exe':
    author            => 'company',
    repository        => 'example',
    release           => '0.0.2',
    asset             => true,
    asset_filepattern => 'example.*\.exe'
}

This will download the first file matching the given filepattern.

All patterns are Regular Expressions.

This module also supports hiera. Just include the githubreleases-class and use the type like this:

githubreleases::download:
  '/tmp/release.latest.head.fromhiera.tar.gz':
    author: 'company'
    repository: 'example'

Using authentication

Github rate-limits access to its API. If you use this module in a test and massively download files using it, you better create a Github user and set the authentication parameters so that you will get a better rate.

Reference

class githubreleases

This will set basic parameters for all further githubreleases::download usages.

• author: The github author (e.g. company)
• repository: The github repository by the author (e.g. example)
• release: The desired release [defaults to latest]
• asset: Use asset filtering [defaults to false]
• asset_fallback: If the asset could not be found, use the tar/zipball-link instead. [defaults to false]
• use_zip: Download zipballs instead of tarballs [defaults to false]
• asset_filepattern: A string in regular expression format filtering the file name of the asset [defaults to .*]
• asset_contenttype: A string in regular expression format filtering the contenttype of the asset [defaults to .*]
• is_tag: The given release is not a name of a release but rather the corresponding tag [defaults to false]
• use_auth: Use authentication when talking to the Github API [defaults to false]
• username: A github username to use when talking to the github API
• password: A github password (personal auth tokens work, too) to use when talking to the github API

type githubreleases::download

This type will actually download the desired file from github. The parameters are the same like in the githubreleases class, plus

• target: The target file where to put the download [defaults to the type name]