README
¶
| 
|
Frizbee
Frizbee is a tool you may throw a tag at and it comes back with a checksum.
It's a command-line tool designed to provide checksums for GitHub Actions and container images based on tags.
It also includes a set of libraries for working with tags and checksums.
Table of Contents
Installation
To install Frizbee, you can use the following methods:
# Using Go
go get -u github.com/stacklok/frizbee
go install github.com/stacklok/frizbee
# Using Homebrew
brew install stacklok/tap/frizbee
# Using winget
winget install stacklok.frizbee
Usage - CLI
GitHub Actions
Frizbee can be used to generate checksums for GitHub Actions. This is useful for verifying that the contents of a GitHub Action have not changed.
To quickly replace the GitHub Action references for your project, you can use
the actions command:
frizbee actions path/to/your/repo/.github/workflows/
This will write all the replacements to the files in the directory provided.
Note that this command will only replace the uses field of the GitHub Action
references.
Note that this command supports dry-run mode, which will print the replacements to stdout instead of writing them to the files.
It also supports exiting with a non-zero exit code if any replacements are found. This is handy for CI/CD pipelines.
If you want to generate the replacement for a single GitHub Action, you can use the same command:
frizbee actions metal-toolbox/container-push/.github/workflows/container-push.yml@main
This is useful if you're developing and want to quickly test the replacement.
Container Images
Frizbee can be used to generate checksums for container images. This is useful
for verifying that the contents of a container image have not changed. This works
for all yaml/yml and Dockerfile fies in the directory provided by the -d flag.
To quickly replace the container image references for your project, you can use
the image command:
frizbee image path/to/your/yaml/files/
To get the digest for a single image tag, you can use the same command:
frizbee image ghcr.io/stacklok/minder/server:latest
This will print the image reference with the digest for the image tag provided.
Usage - Library
Frizbee can also be used as a library. The library provides a set of functions for working with tags and checksums. Here are a few examples of how you can use the library:
GitHub Actions
// Create a new replacer
r := replacer.NewGitHubActionsReplacer(config.DefaultConfig())
...
// Parse a single GitHub Action reference
ret, err := r.ParseString(ctx, ghActionRef)
...
// Parse all GitHub Actions workflow yaml files in a given directory
res, err := r.ParsePath(ctx, dir)
...
// Parse and replace all GitHub Actions references in the provided file system
res, err := r.ParsePathInFS(ctx, bfs, base)
...
// Parse a single yaml file referencing GitHub Actions
res, err := r.ParseFile(ctx, fileHandler)
...
// List all GitHub Actions referenced in the given directory
res, err := r.ListPath(dir)
...
// List all GitHub Actions referenced in the provided file system
res, err := r.ListPathInFS(bfs, base)
...
// List all GitHub Actions referenced in the provided file
res, err := r.ListFile(fileHandler)
Container images
// Create a new replacer
r := replacer.NewContainerImagesReplacer(config.DefaultConfig())
...
// Parse a single container image reference
ret, err := r.ParseString(ctx, ghActionRef)
...
// Parse all files containing container image references in a given directory
res, err := r.ParsePath(ctx, dir)
...
// Parse and replace all container image references in the provided file system
res, err := r.ParsePathInFS(ctx, bfs, base)
...
// Parse a single yaml file referencing container images
res, err := r.ParseFile(ctx, fileHandler)
...
// List all container images referenced in the given directory
res, err := r.ListPath(dir)
...
// List all container images referenced in the provided file system
res, err := r.ListPathInFS(bfs, base)
...
// List all container images referenced in the provided file
res, err := r.ListFile(fileHandler)
Configuration
Frizbee can be configured by setting up a .frizbee.yml file.
You can configure Frizbee to skip processing certain actions, i.e.
ghactions:
exclude:
# Exclude the SLSA GitHub Generator workflow.
# See https://github.com/slsa-framework/slsa-github-generator/issues/2993
- slsa-framework/slsa-github-generator/.github/workflows/generator_generic_slsa3.yml
Similarly, you can exclude actions that are referenced using a particular branch:
ghactions:
exclude_branches:
- main
- master
By default, Frizbee will exclude all actions that are referenced by a branch and only pin actions that are referenced by a tag.
You can also configure Frizbee to skip processing certain container images or certain tags:
images:
exclude_images:
- busybox
exclude_tags:
- devel
By default, Frizbee will exclude the image named scratch and the tag latest.
Contributing
We welcome contributions to Frizbee. Please see our Contributing guide for more information.
License
Frizbee is licensed under the Apache 2.0 License.
Documentation
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package cmd provides the frizbee command line interface.
|
Package cmd provides the frizbee command line interface. |
|
actions
Package actions provides command-line utilities to work with GitHub Actions.
|
Package actions provides command-line utilities to work with GitHub Actions. |
|
image
Package image provides command-line utilities to work with container images.
|
Package image provides command-line utilities to work with container images. |
|
version
Package version adds a version command.
|
Package version adds a version command. |
|
internal
|
|
|
cli
Package cli provides utilities to work with the command-line interface.
|
Package cli provides utilities to work with the command-line interface. |
|
traverse
Package traverse provides utilities to traverse directories.
|
Package traverse provides utilities to traverse directories. |
|
pkg
|
|
|
interfaces
Package interfaces provides interfaces for the frizbee package.
|
Package interfaces provides interfaces for the frizbee package. |
|
replacer
Package replacer provide common replacer implementation
|
Package replacer provide common replacer implementation |
|
replacer/actions
Package actions provides utilities to work with GitHub Actions.
|
Package actions provides utilities to work with GitHub Actions. |
|
replacer/image
Package image provides utilities to work with container images.
|
Package image provides utilities to work with container images. |
|
utils/config
Package config provides the frizbee configuration.
|
Package config provides the frizbee configuration. |
|
utils/ghrest
Package ghrest provides a wrapper around the go-github client that implements the internal REST API
|
Package ghrest provides a wrapper around the go-github client that implements the internal REST API |
|
utils/store
Package store provides utilities to work with a cache store.
|
Package store provides utilities to work with a cache store. |