baseliner

module
v0.1.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 17, 2026 License: MIT

README

baseliner

CI Release Go Reference Go Report Card

baseliner is a single-binary CLI that scans a fleet of repositories for baseline compliance and reports findings as JSON and/or a console summary. It runs against local git checkouts and/or GitHub org/user scopes, and can optionally open a findings issue per repository.

Current capabilities

  • Discovers repositories from local paths and/or GitHub org/user scope.
  • Collects filesystem and git metadata into a normalized repository model.
  • Evaluates a built-in default policy with 10 checks.
  • Outputs results as JSON, table, or both.
  • Optionally opens/updates a GitHub findings issue on repos that have findings, and closes it when a repo becomes compliant (--open-issues).

Requirements

  • None for the prebuilt binary — it is statically linked, no runtime needed.
  • GitHub scanning and --open-issues require a GitHub token in your configured env var (default: GITHUB_TOKEN).

Install

# Install script (Linux/macOS) — installs to ~/.local/bin:
curl -fsSL https://raw.githubusercontent.com/baselinerhq/baseliner/main/scripts/install.sh | bash

# Or with the Go toolchain:
go install github.com/baselinerhq/baseliner/cmd/baseliner@latest

Prebuilt archives for Linux/macOS/Windows (amd64/arm64) are on the releases page. See docs/install.md for all options (including the planned Homebrew tap).

Quick start (local)

Create a minimal baseliner.yaml:

scope:
  local:
    paths:
      - .
policy:
  base: default

Run a scan:

baseliner scan --config baseliner.yaml --format table

Quick start (GitHub)

Use the example config and edit it for your org/user:

cp examples/baseliner.yaml baseliner.yaml
export GITHUB_TOKEN=<your_pat>
baseliner scan --config baseliner.yaml --format both --output-file results.json
Scan flags
Flag Default Description
--config PATH baseliner.yaml Path to config file
--output-file PATH unset Write JSON results to file
--format both json, table, or both
--open-issues off Open/update a findings issue on repos with findings; close it when a repo is compliant
--dry-run off Skip API write calls
--verbose off Debug logging
--quiet off Suppress table output; keep errors
Exit codes
Code Meaning
0 Scan completed and all repos passed
1 Scan completed with one or more failing repos
2 Runtime/config/auth/discovery error

Control Repo Setup

baseliner is designed to run from a dedicated control repo that owns the scan config and scheduled workflow.

Prerequisites

  • A GitHub token with access to all target repos.

  • If using a fine-grained token, grant:

    Permission Level Why
    Metadata Read Org/user repo discovery
    Contents Read File checks via Contents API
    Issues Write Required only when using --open-issues

  • For orgs with SAML SSO, authorize the token for that org after creating it.

Steps
  1. In your control repo, copy the workflow template: 
    mkdir -p .github/workflows
curl -fsSL https://raw.githubusercontent.com/baselinerhq/baseliner/main/examples/control-repo-workflow.yml \
  -o .github/workflows/baseliner.yml
  2. Copy and edit the config: 
    curl -fsSL https://raw.githubusercontent.com/baselinerhq/baseliner/main/examples/baseliner.yaml \
  -o baseliner.yaml
  3. Add repo secret BASELINER_TOKEN in GitHub Actions settings.
  4. Trigger workflow_dispatch and confirm results.json uploads as an artifact.

Docs

License

MIT. See LICENSE.

Directories

Path Synopsis
cmd
baseliner command
Command baseliner scans repositories for baseline compliance.
 Command baseliner scans repositories for baseline compliance.
internal
actions
Package actions performs side-effecting operations from scan results.
 Package actions performs side-effecting operations from scan results.
checks
Package checks implements the baseliner compliance checks and a registry.
 Package checks implements the baseliner compliance checks and a registry.
collectors
Package collectors builds NormalizedRepository values from local filesystem, local git, and the GitHub API.
 Package collectors builds NormalizedRepository values from local filesystem, local git, and the GitHub API.
config
Package config loads and validates baseliner.yaml.
 Package config loads and validates baseliner.yaml.
discovery
Package discovery finds repositories to scan from local paths or GitHub.
 Package discovery finds repositories to scan from local paths or GitHub.
engine
Package engine evaluates repositories against a policy and scores them.
 Package engine evaluates repositories against a policy and scores them.
models
output
Package output renders scan results as a console summary and as JSON.
 Package output renders scan results as a console summary and as JSON.
policy
Package policy loads baseliner policies.
 Package policy loads baseliner policies.
runner
Package runner orchestrates a scan: config -> discovery -> collect -> evaluate -> output -> (issues).
 Package runner orchestrates a scan: config -> discovery -> collect -> evaluate -> output -> (issues).
source
Package source defines RepoSource, the output of discovery and input to collectors.
 Package source defines RepoSource, the output of discovery and input to collectors.
version
Package version holds the baseliner build version.
 Package version holds the baseliner build version.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.