Skip to content

Latest commit

 

History

History
208 lines (157 loc) · 6.5 KB

README.md

File metadata and controls

208 lines (157 loc) · 6.5 KB
Raw

image

Coverage Status | License: Apache 2.0 |

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.

Frizbee is available as a GitHub Action: frizbee-action

Table of Contents

Installation

To install Frizbee, you can use the following methods:

# Using Go
go install github.com/stacklok/[email protected]
# add the path to your .bashrc
export PATH=$PATH:$(go env GOPATH)/bin



# Using Homebrew
brew install 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 referencing main or master.

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 & Community

Frizbee is maintained by a dedicated community of developers that want this open souce project to benefit others and thrive. The main development of Frizbee is done in Go. We welcome contributions of all types! Please see our Contributing guide for more information on how you can help!

If you have questions, or just want to chat with us - please use the #frizbee channel on our Discord Server.

License

Frizbee is licensed under the Apache 2.0 License.