GitHub File

A GitHub artifact is a reference to a file stored in GitHub or GitHub Enterprise.

These artifacts are generally consumed by stages that read configuration from text files, such as a “Deploy (Manifest)” stage.

GitHub file artifact in the UI

The pipeline UI exposes the following fields for the GitHub file artifact:

FieldExplanation
AccountA GitHub artifact account.
File pathThe path to the artifact file, beginning at the root of the Git repository.
Content URLThe GitHub API content URL for the artifact file.
Commit/BranchThe commit hash or branch name to use when retrieving the artifact file from GitHub.

In a trigger

When configuring a Git trigger with Type “GitHub”, you can use a GitHub file as an expected artifact.

Configuring GitHub file fields in a pipeline trigger’s expected artifact settings.

Configuring GitHub file fields in a pipeline trigger’s expected artifact settings.

In a pipeline stage

When configuring certain stages, such as a “Deploy (Manifest)” or “Deploy” stage, you can use a GitHub file as a manifest or application artifact. You can either use a previously-defined artifact (for example, an artifact defined in a trigger) or define an artifact inline.

Configuring a Deploy (Manifest) stage to use a GitHub file as a manifest source.

Configuring a Deploy (Manifest) stage to use a GitHub file as a manifest source.

GitHub file artifact in a pipeline definition

The following are the fields that make up a GitHub file artifact:

FieldExplanation
typeAlways github/file.
referenceThe full path (including filename) for retrieval via the GitHub API. This is the contents_url referenced by a PushEvent .

GitHub example: https://api.github.com/repos/myorg/myrepo/contents/path/to/file.yml.
GHE example: https://github.mydomain.com/api/v3/repos/myorg/myrepo/contents/path/to/file.yml.
nameThe path to the artifact file, beginning at the root of the Git repository. Example: path/to/file.yml.
versionThe commit hash, branch name, or tag to use when retrieving the artifact file from GitHub.
locationN/A

The following is an example JSON representation of a GitHub file artifact, as it would appear in a pipeline definition:

{
  "type": "github/file",
  "reference": "https://api.github.com/repos/myorg/myrepo/contents/path/to/file.yml",
  "name": "path/to/file.yml",
  "version": "aec855f4e0e11"
}