A Go command line interface for managing code ownership and project insights with OpenSauced!
Watch the overview video π
π¦ Install
brew install open-sauced/tap/pizza
npm i -g pizza
You can also use npx
to run one-off commands without installing anything:
npx pizza@latest generate codeowners .
Using the Go tool-chain, you can install the binary directly:
$ go install github.com/open-sauced/pizza-cli@latest
Warning
Warning! You should have the GOBIN
env var setup to point to a persistent
location in your PATH
. After Go 1.16, this defaults to GOPATH[0]/bin
.
Download a pre-built artifact from the GitHub releases:
# Make the binary executable
$ chmod +x ~/Downloads/pizza-linux-arm64
# Move the binary into a location in the PATH
# Warning: the location where you drop the binary may differ!
$ mv ~/Downloads/pizza-linux-arm64 /usr/local/share/bin/pizza
curl -fsSL https://raw.githubusercontent.com/open-sauced/pizza-cli/main/install.sh | sh
This is a convenience script that can be downloaded from GitHub directly and
piped into sh
for conveniently downloading the latest GitHub release of the
pizza
CLI.
Once download is completed, you can move the binary to a convenient location in
your system's $PATH
.
Warning
It's probably not advisable to pipe scripts from GitHub directly into a command line interpreter! If you do not fully trust the source, first download the script, inspect it manually to ensure integrity, and then run it:
curl -fsSL https://raw.githubusercontent.com/open-sauced/pizza-cli/main/install.sh > install.sh
vim install.sh
./install.sh
Use the container image of the CLI for use in CI/CD or automation:
$ docker run ghcr.io/open-sauced/pizza-cli:latest
For commands that require access to your file system (like generate codeowners
), ensure
you pass a volume to the docker container:
$ docker run -v /local/path:/container/path ghcr.io/open-sauced/pizza-cli:latest \
generate codeowners /container/path
For example, to mount your entire home directory (which may include a ~/.sauced.yaml
file
alongside the project you want to generate a CODEOWNERS
file for):
$ docker run -v ~/:/app ghcr.io/open-sauced/pizza-cli:latest \
codeowners /app/workspace/gopherlogs -c /app/.sauced.yaml
Use the Pizza GitHub Action for running pizza
operations in GitHub CI/CD,
like automated CODEOWNERS
updating and pruning:
jobs:
pizza-action:
runs-on: ubuntu-latest
steps:
- name: Pizza Action
uses: open-sauced/pizza-action@v2
with:
# Optional: Whether to commit and create a PR for "CODEOWNER" changes
commit-and-pr: "true"
# Optional: Title of the PR for review by team
pr-title: "chore: update repository codeowners"
- Pizza.md: In depth docs on each command, option, and flag.
- OpenSauced.pizza/docs: Learn how to use the Pizza command line tool and how it works with the rest of the OpenSauced ecosystem.
Get up and running with the Pizza CLI in minutes using npx
:
-
Ensure you have Node.js installed
Pizza CLI can be run using
npx
, which comes with Node.js. If you don't have Node.js installed, download it from nodejs.org.NOTE For other installation methods, see the Install section.
-
Generate a configuration file
Navigate to your project directory and run:
npx pizza@latest generate config ./ -i
This will create a
.sauced.yaml
file, interactively prompting you to attribute commit emails to GitHub handles. -
Generate CODEOWNERS file
In your project directory, run:
npx pizza@latest generate codeowners ./
This will create a
CODEOWNERS
file based on your project's git history and the.sauced.yaml
configuration. -
Create OpenSauced Contributor Insight
After generating the CODEOWNERS file, you can create an OpenSauced Contributor Insight:
npx pizza@latest generate insight .
-
Explore repository insights Get metrics and insights for your repository:
npx pizza@latest insights repositories your-username/your-repo
-
Set up automated CODEOWNERS updates (Optional) Add the Pizza GitHub Action to your repository to automate CODEOWNERS updates:
# In .github/workflows/pizza-action.yml name: OpenSauced Pizza Action on: schedule: # Run once a week on Sunday at 00:00 UTC - cron: "0 0 * * 0" workflow_dispatch: # Allow manual triggering jobs: pizza-action: runs-on: ubuntu-latest steps: - name: Pizza Action uses: open-sauced/pizza-action@v2.2.0 with: # optional and default is "latest". Add this parameter if you want to use a specific version, e.g. v2.0.0 cli-version: "v2.2.0" # optional and false by default. Set this to true if you want to have a pull request for the changes created automatically. commit-and-pr: "true" # optional pr-title: "chore: update repository codeowners"
Now you're ready to leverage the Pizza CLI for managing code ownership and getting project insights with OpenSauced!
Note Using
npx pizza@latest
ensures you're always running the most recent version of Pizza CLI. If you prefer to use a specific version, you can replace@latest
with a version number, e.g.,npx pizza@2.0.0
.
Use the codeowners
command to generate a GitHub style CODEOWNERS
file or a more agnostic OWNERS
file.
This can be used to granularly define what experts and entities have the
most context and knowledge on certain parts of a codebase.
It's expected that there's a .sauced.yaml
config file in the given path or in
your home directory (as ~/.sauced.yaml
):
pizza generate codeowners /path/to/local/git/repo
Running this command will iterate the git ref-log to determine who to set as a code
owner based on the number of lines changed for that file within the given time range.
The first owner is the entity with the most lines changed. This command uses a .sauced.yaml
configuration
to attribute emails in commits with the given entities in the config (like GitHub usernames or teams).
See the section on the configuration schema for more details
The pizza generate config
command has been added to help you create .sauced.yaml
configuration files for your projects.
This command allows you to generate configuration files with various options:
pizza generate config /path/to/local/git/repo
This command will iterate the git ref-log and inspect email signatures for commits
and, in interactive mode, ask you to attribute those users with GitHub handles. Once finished, the resulting
.sauced.yaml
file can be used to attribute owners in a CODEOWNERS
file during pizza generate codeowners
.
-i, --interactive
: Enter interactive mode to attribute each email manually-o, --output-path string
: Set the directory for the output file-h, --help
: Display help for the command
-
Generate a config file in the current directory:
pizza generate config ./
-
Generate a config file interactively:
pizza generate config ./ -i
-
Generate a config file from the current directory and place resulting
.sauced.yaml
in a specific output directory:pizza generate config ./ -o /path/to/directory
You can create an OpenSauced Contributor Insight
from a local CODEOWNERS
file:
pizza generate insight /path/to/repo/with/CODEOWNERS/file
This will parse the CODEOWNERS
file and create a Contributor Insight on the OpenSauced platform.
This allows you to track insights and metrics for those codeowners, powered by OpenSauced.
You can get metrics and insights on repositories, contributors, and more:
pizza insights [sub-command]
This powerful command lets you compose many metrics and insights together, all
powered by OpenSauced's API. Use the --output
flag to output the results as yaml, json, csv, etc.
# Configuration for attributing commits with emails to individual entities.
# Used during "pizza generate codeowners".
attribution:
# Keys can be GitHub usernames.
jpmcb:
# List of emails associated with the given GitHub login.
# The commits associated with these emails will be attributed to
# this GitHub login in this yaml map. Any number of emails may be listed.
- john@opensauced.pizza
- hello@johncodes.com
# Keys may also be GitHub teams. This is useful for orchestrating multiple
# people to a sole GitHub team.
open-sauced/engineering:
- john@opensauced.pizza
- other-user@email.com
- other-user@no-reply.github.com
# Keys can also be agnostic names which will land as keys in "OWNERS" files
# when the "--owners-style-file" flag is set.
John McBride
- john@opensauced.pizza
# Used during codeowners generation: if there are no code owners found
# for a file within the time range, the list of fallback entities
# will be used
attribution-fallback:
- open-sauced/engineering
- some-other-github-login
There are a few things you'll need to get started:
- The 1.22
go
programming language toolchain and dev environment (for example, the VScode Go plugin is very good). - The
just
command runner for easy operations
Clone this repository. Then, using the Go tool-chain, you can build a binary:
go build -o build/pizza main.go
Warning
There may be unsupported features, breaking changes, or experimental patches on the tip of the repository. Go and build with caution!
There are a number of just
convinence commands for building with injected buildtime variables
and targeting other architectures and operating systems.
just build
just build-all
There are a number of useful just
commands that should be used during development:
just lint
will us Golangci-lint to lint the Go codejust clean
removes build artifacts frombuild/
just test
runs the unit and e2e testsjust format
uses goimports to format code- ... and many more!
Check just help
to get a full list of utility dev commands!