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.