Installing from a Private GitHub Repo

If your governance rules live in a private GitHub repository, use ssg install to fetch and install them directly — no hub account required, no publishing step.

ssg install github.com/<owner>/<repo>

Prerequisites

1. ssg auth login — authenticate with GitHub.

2. repo scope — your token needs repo to read private repo tarballs. Run ssg auth refresh if you originally logged in before this scope was required.

   Note on scope breadth: GitHub's repo scope grants read and write access to all your repositories — there is no read-only variant for private repos in the OAuth Device Flow. ssg install only ever reads from GitHub (it never pushes), but the token itself is broad. If you are concerned about the token's blast radius, consider authenticating with a fine-grained personal access token scoped to the specific repos you want to install from, and storing it in ~/.sigmashake/hosts.toml under the token key.

Basic usage

# Install from the default branch (HEAD)
ssg install github.com/my-org/my-rules

# Install a specific branch or tag
ssg install github.com/my-org/my-rules@main
ssg install github.com/my-org/my-rules@v1.2.0
ssg install github.com/my-org/my-rules@abc1234

Rules are fetched from .sigmashake/rules/ inside the repo and written to .sigmashake/rules/ in your current project.

Flags

Flag	Default	Description
--ref=<branch|tag|sha>	HEAD	Git ref to install from
--dir=<path>	.sigmashake/rules	Path inside the repo where .rules files live
--force	false	Reinstall even if already installed at same SHA

How it works

1. Resolves the ref to a commit SHA via the GitHub API (stable pinning).
2. Downloads the repository tarball (GET /repos/:owner/:repo/tarball/:sha).
3. Extracts .sigmashake/rules/**/*.rules files from the tarball.
4. Copies them into ./.sigmashake/rules/ in your project.
5. Records the commit SHA in .sigmashake/sources.json for update tracking.

No git binary needed — uses the GitHub API and native tarball extraction only.

sources.json — commit pinning

After installation, .sigmashake/sources.json records what was installed:

{
  "sources": {
    "my-org/my-rules": {
      "owner": "my-org",
      "repo": "my-rules",
      "ref": "main",
      "sha": "abc1234...",
      "rulesDir": ".sigmashake/rules",
      "installedAt": "2025-04-15T10:00:00.000Z"
    }
  }
}

Run ssg install github.com/my-org/my-rules --force to re-fetch when the upstream repo changes.

Custom rules directory

If your rules live somewhere other than .sigmashake/rules/:

ssg install github.com/my-org/my-rules --dir=policies/rules

Already installed?

Running ssg install again without --force is a no-op:

ssg install github.com/my-org/my-rules
# my-org/my-rules is already installed (sha: abc1234).
# Run with --force to reinstall, or use `ssg update` to check for upstream changes.

Public repos

Works for public repos too — no repo scope required for public tarballs:

ssg install github.com/my-org/my-public-rules

Comparison to hub pull

	ssg install <github-url>	ssg hub pull <id>
Private repos	✓	✓ (org-private)
Hub account required	—	✓
Integrity verification	SHA pinning	SHA-256 + Ed25519
Update tracking	sources.json	hub version
Team discovery	—	✓ (org members)

For team sharing and discovery, see Organizations & Private Rulesets.