Skip to content

Latest commit

 

History

History
117 lines (78 loc) · 3.58 KB

fetching-files.rst

File metadata and controls

117 lines (78 loc) · 3.58 KB
Raw

Fetching Files

Buildrunner has a fetch facility for retrieving files and artifacts to incorporate into the build.

Usage

The syntax for referencing a back-end uses a simple URL format:

``BACKEND://REPOSITORY/PATH``
BACKEND

The fetch back-end to use: github, http, file, etc.

REPOSITORY

Which location/repository the BACKEND will reference. This is a label that is used as a reference into configuration found in Buildrunner configuration files (e.g. ~/.buildrunner.yaml) where a full description of connection parameters and available (see specific documentation for each fetch module).

PATH

The unique path or ID of the artifact found in the REPOSITORY.

Fetch Backends

The available fetch back-ends are the following:

  • Github: fetches files from Github
  • File: fetches files from the file system
  • HTTP/HTTPS: fetches files from HTTP/HTTPS servers

Github

Files can be retrieved from Github - either central github.com location or GitHub Enterprise servers. The fetch syntax is the following:

github://LABEL/GROUP/REPO/PATH

:github://: scheme indicates fetching using the github facility. :LABEL: a look-up key into Buildrunner configuration that describes connection parameters. This is an arbitrary name but benefits from uniform use across build sources. :GROUP: Github organization/group. :REPO: Git repository in the GROUP. :PATH: path to the file in the Git REPO.

The github:// facility requires the following configuration entries:

github:
  LABEL:
    endpoint: 'https://HOSTNAME/API_PATH'
    version: 'VERSION'
    username: 'USERNAME'
    app_token: 'APP_TOKEN'

The following is suggested for an entry to reference files for GitHub Enterprise:

github:
  company_github:
    endpoint: 'https://git.company.com/api'
    version: 'v3'
    username: 'USERNAME'
    app_token: 'APP_TOKEN'
username

The individual username used to access the Github Enterprise instance.

app_token

The user-specific application token generated by the user on Github for Buildrunner access. It is a 40 hex digit token.

File

Files can be retrieved from the local file system. The initial file:// scheme is optional. These two are equivalent:

  • file:///some/path/to/a/file.ext
  • /some/path/to/a/file.ext

If a relative path from the source directory is to be designated then the file:// scheme cannot be used:

relative/path/to/a/file.ext

HTTP/HTTPS

This is stubbed-out and not yet implemented.

Redirecting buildrunner.yaml

The buildrunner.yaml file can be retrieved from a remote location using the fetch facility. This allows a collection of builds to have a centrally-managed buildrunner.yaml which avoids problems in updating and synchronizing copies to possibly unknown locations.

To redirect buildrunner.yaml only a single entry should be in the file:

redirect: 'github://gh-label/org/repo/sample-buildrunner.yaml'

Buildrunner will repeatedly redirect, fetch and interpret the new buildrunner.yaml until it finds one that no longer finds a redirect directive. At that point it will interpret the final buildrunner.yaml. It will not merge entries from earlier, redirecting buildrunner.yaml files - all other content is ignored when the redirect directive is found.