isabella232 / watchdog4git

A GitHub 🤖 that checks for common Git related errors and notifies the responsible engineers

Watchdog4Git

Watchdog4Git is a bot 🤖 that checks commits pushed to GitHub for common Git problems. If the bot identifies a problem, then it notifies the committer by posting a comment to the commit.

Currently Watchdog4Git checks only for Git LFS related problems. The watchdog warns if large files are added to the repository that should be tracked by Git LFS.

In the future Watchdog4Git could also check for Git Submodule problems, .gitignore problems, and other Git related problems.

Getting started

1. Build Watchdog4Git:

make

1. Deploy the watchdog4git executable to a server.
2. Run Watchdog4Git on the server.
3. Create and install a watchdog4git GitHub App and point it to your server.
4. Add a .github/watchdog.yml file to your repository that configures the Git LFS checks:

# Contact for users in notification comments (can include GitHub @mentions)
helpContact: "[#your-channel](https://yourcompany.slack.com/messages/ABC1234)"

# General size threshold for files that should be in Git LFS
# (uncompressed size in bytes)
lfsSizeThreshold: 512000

# List of files that are exempt from the general size threshold
# (typically large text files, optional)
lfsSizeExemptions: |
    testdata/largetext.txt
    *.xml
    
# Size threshold for exempt files that should be in Git LFS
# (uncompressed size in bytes, optional)
lfsSizeExemptionsThreshold: 20000000

# Switch to turn on/off Git LFS file size suggestions
lfsSuggestionsEnabled: Yes

How does it work?

Watchdog4Git receives GitHub webhook events for every push. The payload contains a list of commits whose metadata contain the list of added, modified, and deleted files.

For each added or modified file in each commit, the App queries the file size and checks if the file does not match a Git LFS path pattern but is larger than the defined threshold. It then marks the file as a suggestion. All suggestions are rolled up in a single commit comment and posted to the commit on GitHub.

Contributors

These are the humans that develop Watchdog4Git:

@larsxschneider	@mlbright

License

SPDX-License-Identifier: MIT