Judges Zerocracy Action

First, get a free authentication token from Zerocracy.com and add it as ZEROCRACY_TOKEN secret to your repository.

Then, create a new personal access token and add it as a ZEROCRACY_PAT secret to your repository. Don't forget to give it full "repository access". You may ignore this, if all your repositories are public.

Then, add this zerocracy.yml file to your GitHub repository at the .github/workflows/ directory (replace foo with the name of your team, yegor256 with the name of the account owner, and 42 with anything between zero and 60):

name: zerocracy
'on':
  schedule:
    - cron: '42 * * * *'
concurrency:
  group: zerocracy
  cancel-in-progress: false
jobs:
  zerocracy:
    if: github.repository_owner == 'yegor256'
    runs-on: ubuntu-24.04
    timeout-minutes: 25
    steps:
      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
      - uses: zerocracy/judges-action@0.17.21
        with:
          token: ${{ secrets.ZEROCRACY_TOKEN }}
          github-token: ${{ secrets.ZEROCRACY_PAT }}
          repositories: yegor256/foo
          factbase: foo.fb
      - uses: zerocracy/pages-action@0.7.0
        with:
          github-token: ${{ secrets.ZEROCRACY_PAT }}
          factbase: foo.fb
      - uses: JamesIves/github-pages-deploy-action@ec9c88baef04b842ca6f0a132fd61c762aa6c1b0 # v4.6.0
        with:
          folder: pages
          clean: false

In the file, there is only one place that you should configure: the repositories=... should have a comma-separated list of repositories where your team works (instead of ...). If you have more than one repository in your product, list them here. The CI job must only be added to one of them.

Once the file is added, GitHub starts running this job hourly, collecting information about most important activities of your programmers. The plugin gives them awards for good things they do (like fixing bugs) and also punishes them (by deducting points) for bad things (like stale pull requests).

The plugin also generates a summary foo-vitals.html file in the output directory of pages-action (pages by default), which is automatically deployed to the gh-pages branch. You can configure your GitHub repository to render the branch as a static website via GitHub Pages. Thus, the summary page is updated hourly and you see who is subjectively the best performer in your team, similar to what we see in our team.

Configuration

The following action inputs are set via with: in your workflow YAML (see how we configure it):

• token (mandatory) is an authentication token from Zerocracy.com
• options (optional) is a list of k=v pairs for advanced tuning, explained below
• factbase (optional, default is default.fb) is the path of the Factbase file (where everything is kept)
• repositories (optional) is a comma-separated list of masks that determine the repositories to manage, where yegor256/* means all repos of the user, yegor256/judges means a specific repo, and -yegor256/judges means an exclusion of the repo from the list.
• github-token (optional) is an authentication GitHub access token
• verbose (optional) makes it print debugging info if set to true
• fail-fast (optional) stops after the first error if set to true
• dry-run (optional) skips all judges and makes no changes if set to true
• timeout (optional) is how many minutes each judge can spend
• lifetime (optional) is how many minutes the entire update can take
• cycles (optional) is a number of update cycles to run, default is 2
• sqlite-cache (optional) is a path of SQLite database file with HTTP cache
• bots (optional) is a comma-separated list of GitHub user logins to mark as bots

Some parameters are configurable both as an action input above and as a k=v pair in options below (the pairs exist for backward compatibility and advanced scenarios). When both are set, the github_token= and bots= pairs win over the github-token and bots inputs, while the repositories and sqlite-cache inputs win over the repositories= and sqlite_cache= pairs:

• github_token=... is a default GitHub token, usually to be set to ${{ secrets.GITHUB_TOKEN }}; the github-token action input is ignored when this pair is set
• repositories=.. is a comma-separated list of masks, where yegor256/* means all repos of the user, yegor256/judges means a specific repo, and -yegor256/judges means an exclusion of the repo from the list; the repositories action input overrides this pair, and so does the current repository when that input is empty
• bots=... is a comma-separated list of GitHub user logins to mark as bots; the bots action input is ignored when this pair is set
• sqlite_cache_maxsize=10M is the maximum size of HTTP cache file
• sqlite_cache_maxvsize=10K is the maximum size of a single HTTP entry to cache (these two are only available as k=v pairs)
• sqlite_cache_min_age=3600 is the minimum age in seconds before a cached HTTP response is considered stale (default is 3600, i.e. 1 hour)

Environment Variables

The following environment variables are recognized by the Docker entry point:

• SKIP_VERSION_CHECKING (optional, default is unset) if set to true, skips the version compatibility check against GitHub releases. Useful for development, testing with a non-release build, air-gapped environments, or faster CI when version checking is not critical.

Note: job_id, action_version, and vitals_url are automatically populated by the entry point and should not be set manually.

The zerocracy/pages-action plugin is responsible for rendering the summary HTML page: its configuration is not explained here, check its own repository.

How to Contribute

You need to have GNU Bash 5+, GNU Make 4+, Ruby 3+, Bundler, and GNU parallel installed.

Then, just run:

bundle update
make

This should build a new Docker image named judges-action and then run the entire cycle inside a new Docker container. Obviously, you need to have Docker installed. The Docker image is deleted by the end of the build (either success or failure).

In order to run "live" tests of some judges, do this:

bundle exec rake -- --live

In order to run a single test, try this:

bundle exec ruby test/judges/test-dimensions-of-terrain.rb -n test_total_repositories