github

README

GitHub Collector README

Overview

The GitHub Collector is a component of the GUAC project designed to download metadata documents stored in GitHub releases or workflow artifacts.

How It Works

The collector can operate in two modes:

1. Release Mode: Targets specific releases within a GitHub repository to collect assets matching predefined suffixes.
2. Workflow Mode: Targets artifacts generated by GitHub Actions workflows within a specific repository.

In both modes, the collector utilizes a GitHub client to interact with the GitHub API, fetching releases or workflow runs and their associated assets. The collected documents are stored in a blob store.

Running the GitHub Collector

Note: For the collector to run, guacIngest along with a pubsub and a blob store are required.

Prerequisites

• A valid GitHub token set in the environment variable GITHUB_TOKEN.

Command Line Interface

The GitHub Collector is invoked through the guaccollect command-line interface. The specific subcommand for the GitHub collector is github.

Release Mode

guaccollect github --github-mode release [flags] <RELEASE_URL_1> <RELEASE_URL_2> ...

• <RELEASE_URL_1>, <RELEASE_URL_2>, ...: URLs of the GitHub releases to collect.

Workflow Mode

guaccollect github --github-mode=workflow --github-workflow-file=<WORKFLOW_FILE_NAME> [flags] <OWNER>/<REPO>

• <WORKFLOW_FILE_NAME>: Name of the workflow file to target for artifact collection.
• <OWNER>/<REPO>: GitHub repository in the format owner/repo.

Flags

• --github-mode: Mode of operation (release or workflow). Default is release.
• --github-sbom: (Workflow mode) Name of the SBOM file to collect.
• --github-workflow-file: (Workflow mode) Name of the GitHub Actions workflow file.

Configuration

The GitHub Collector can be further configured through environment variables and command-line flags to adjust polling intervals and more. For detailed configuration options, refer to the source code documentation and help output of the guaccollect github command.

Documentation

Index

• Constants
• func NewGithubCollector(opts ...Opt) (*githubCollector, error)
• type Config
• type Opt
  • func WithAssetSuffixes(assetSuffixes []string) Opt
  • func WithClient(client githubclient.GithubClient) Opt
  • func WithCollectDataSource(collectDataSource datasource.CollectSource) Opt
  • func WithMode(githubMode string) Opt
  • func WithOwner(owner string) Opt
  • func WithPolling(interval time.Duration) Opt
  • func WithRelease(isRelease bool) Opt
  • func WithRepo(repo string) Opt
  • func WithRepoToReleaseTags(repoToReleaseTags map[client.Repo][]TagOrLatest) Opt
  • func WithSbomName(sbomName string) Opt
  • func WithWorkflowName(workflowName string) Opt
• type TagOrLatest
  • func ParseGitDataSource(source datasource.Source) (*client.Repo, TagOrLatest, error)
  • func ParseGithubReleaseDataSource(source datasource.Source) (*client.Repo, TagOrLatest, error)

Constants

const (
	GithubCollector = "GithubCollector"
	Latest          = ""
)

Functions

func NewGithubCollector

func NewGithubCollector(opts ...Opt) (*githubCollector, error)

Types

type Config

type Config struct {
	Poll              bool
	Interval          time.Duration
	Client            githubclient.GithubClient
	RepoToReleaseTags map[client.Repo][]TagOrLatest
	AssetSuffixes     []string
	CollectDataSource datasource.CollectSource
}

type Opt

type Opt func(*githubCollector)

func WithAssetSuffixes

func WithAssetSuffixes(assetSuffixes []string) Opt

func WithClient

func WithClient(client githubclient.GithubClient) Opt

func WithCollectDataSource

func WithCollectDataSource(collectDataSource datasource.CollectSource) Opt

func WithMode

func WithMode(githubMode string) Opt

func WithOwner

func WithOwner(owner string) Opt

func WithPolling

func WithPolling(interval time.Duration) Opt

func WithRelease

func WithRelease(isRelease bool) Opt

func WithRepo

func WithRepo(repo string) Opt

func WithRepoToReleaseTags

func WithRepoToReleaseTags(repoToReleaseTags map[client.Repo][]TagOrLatest) Opt

func WithSbomName

func WithSbomName(sbomName string) Opt

func WithWorkflowName

func WithWorkflowName(workflowName string) Opt

type TagOrLatest

type TagOrLatest = string

TagOrLatest is either a tag or if it's the empty string "" then it should be considered latest

func ParseGitDataSource

func ParseGitDataSource(source datasource.Source) (*client.Repo, TagOrLatest, error)

ParseGitDataSource takes in a data URL should be in the form: <vcs_tool>+<transport>://<host_name>[/<path_to_repository>][@<revision_tag_or_branch>][#<sub_path>]

func ParseGithubReleaseDataSource

func ParseGithubReleaseDataSource(source datasource.Source) (*client.Repo, TagOrLatest, error)

ParseGithubReleaseDataSource takes in a data source and parses it assuming it's a Github URL