Sanad

Make native GitHub Actions lockfiles easy to adopt, review, and update.

Sanad manages GitHub's native actions.lock. It generates lockfiles, explains dependency changes, applies update policies, and verifies them in CI. GitHub enforces the locked commits when workflows run.

Requires native lockfile support for your repository. Native lockfiles are in GitHub's public preview.

CLI quickstart

Install with Homebrew:

brew install --cask MohamedElashri/sanad/sanad

Or download a v1.0.1 archive for Linux, macOS, or Windows on amd64/arm64. Keep the included sanad and gh-actions-lock executables together on your PATH.

In your repository, authenticate and review the initial lockfile:

gh auth login
sanad init --confirm-native
sanad init --confirm-native --write
sanad check

--confirm-native records that you verified GitHub supports enforcement for this repository. Review the preview before writing, then commit .github/workflows/actions.lock and .sanad.toml. Authentication also accepts GH_TOKEN or GITHUB_TOKEN.

Action quickstart

Add .github/workflows/sanad.yml to check pull requests:

name: Sanad
on: pull_request
permissions:
  contents: read
jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          fetch-depth: 0
      - uses: MohamedElashri/sanad@a73376eda34400ec92e51fcefec6ee287871da38 # v1.0.1
        with:
          mode: check
          base: ${{ github.event.pull_request.base.sha }}

Run sanad sync --write after adding the workflow and commit the updated lockfile. Make the Sanad check required in repository settings. The Action installs its matching CLI release and verifies its checksum and immutability.

See CI setup for generated workflows and scheduled update PRs, or the Action reference for inputs and outputs.

Everyday use

sanad sync                  # preview reconciliation after workflow edits
sanad sync --write           # apply it without advancing existing pins
sanad plan                  # review available stable version updates
sanad update --write         # apply eligible updates
sanad check                  # online frozen verification
sanad check --offline        # local coverage and graph checks only

Repository changes require --write. Updates stay within the current major version by default. Optional constraints and waiting periods cover direct and transitive dependencies; see configuration reference.

Coding agents

Install the reusable Sanad skill for Codex, Claude Code, Cursor, GitHub Copilot, Antigravity, or OpenCode by copying the skill directory into your agent's skill location. For example, from a Sanad checkout, install it for your user in Codex:

mkdir -p "$HOME/.agents/skills"
cp -R skills/sanad "$HOME/.agents/skills/"

The skill covers onboarding, workflow reconciliation, scoped updates, and verification. It requires Sanad 1.x on the agent's PATH. See the agent guide for each agent's installation paths and example requests, or read SKILL.md.

Documentation · Security and limitations · Release notes · MIT license

Development

Requires Go 1.26.3+ and Node.js 24+.

make check
npm ci --prefix action
npm test --prefix action