binstaller

README

binstaller

binstaller

A modern, secure binary installer generator with enhanced security features

---

binstaller (binst) is a modern binary installer generator that creates secure, reproducible installation scripts for static binaries distributed via GitHub releases. Works with Go binaries, Rust binaries, and any other static binaries - as long as they're released on GitHub, binstaller can generate installation scripts for them.

🔄 How it Works

binstaller follows a simple two-step workflow:

graph LR
    A[GoReleaser config] --> |binst init| C[.binstaller.yml]
    B[GitHub releases] --> |binst init| C
    D[Aqua registry] --> |binst init| C
    E[Manual editing] --> C

    C --> |binst gen| F[Installation script]

    style C fill:#e1f5fe
    style F fill:#f3e5f5

Step 1: binst init - Generate a .binstaller.yml config from various sources Step 2 (Optional): binst embed-checksums - Embed checksums into the config for enhanced security Step 3: binst gen - Generate the final installation script

✨ Key Features

• 🛡️ Enhanced Security: Optional checksum embedding for enhanced verification
• 🔧 Multiple Sources: Support for GoReleaser, GitHub releases, and Aqua registry
• 📦 Flexible Configuration: YAML-based .binstaller.yml configuration files
• 🎯 Cross-Platform: Works across Linux, macOS, Windows, and other Unix-like systems
• ⚡ Fast Installation: Dramatically faster than go install (up to 100x improvement)
• 🔁 Reproducible Builds: Generate consistent installation scripts with source traceability
• 🌐 Universal Support: Works with any static binary on GitHub releases (Go, Rust, C++, etc.)

📦 Installation

🎉 You can install binstaller using a binstaller-generated script!

Release Installer

Official installers generated by actionutils/trusted-go-releaser release workflow, which uses binstaller itself to create these secure installers. These installers provide a chain of trust:

• Generated with binst gen --target-version for specific release versions only
• Contains embedded checksums that were cryptographically verified during installer generation
• The trusted-go-releaser workflow creates attestations for both the installer script and the binary
• Key benefit: When you verify the installer script's attestation, you're also verifying:
  • The embedded checksums are authentic (came from the trusted release process)
  • The binary that will be installed matches these verified checksums
  • No additional verification needed after installation

Install (Latest)

# With GitHub Attestation verification (recommended)
curl -sL https://github.com/binary-install/binstaller/releases/latest/download/install.sh | \
    (tmpfile=$(mktemp); cat > "$tmpfile"; \
     gh attestation verify --repo=binary-install/binstaller --signer-workflow='actionutils/trusted-go-releaser/.github/workflows/trusted-release-workflow.yml' "$tmpfile" && \
     sh "$tmpfile"; rm -f "$tmpfile")

Install (Specific Version)

# Set the desired version
VERSION="v0.1.0"

# Install with attestation verification
curl -sL "https://github.com/binary-install/binstaller/releases/download/${VERSION}/install.sh" | \
    (tmpfile=$(mktemp); cat > "$tmpfile"; \
     gh attestation verify --repo=binary-install/binstaller --signer-workflow='actionutils/trusted-go-releaser/.github/workflows/trusted-release-workflow.yml' "$tmpfile" && \
     sh "$tmpfile"; rm -f "$tmpfile")

Install (Custom Directory)

# Set installation directory (defaults to ${BINSTALLER_BIN:-${HOME}/.local/bin})
INSTALL_DIR="/usr/local/bin"  # or any custom directory

# With GitHub Attestation verification
curl -sL https://github.com/binary-install/binstaller/releases/latest/download/install.sh | \
    (tmpfile=$(mktemp); cat > "$tmpfile"; \
     gh attestation verify --repo=binary-install/binstaller --signer-workflow='actionutils/trusted-go-releaser/.github/workflows/trusted-release-workflow.yml' "$tmpfile" && \
     sh "$tmpfile" -b "$INSTALL_DIR"; rm -f "$tmpfile")

Note: By default, binaries are installed to:

• $BINSTALLER_BIN if set, otherwise
• $HOME/.local/bin (following XDG Base Directory Specification)

Generic Installer

# Optional: Set version (latest if empty)
VERSION="" # e.g., "v0.1.0" or leave empty for latest

# Install from main branch with attestation verification
curl -sL https://raw.githubusercontent.com/binary-install/binstaller/main/install.sh | \
    (tmpfile=$(mktemp); cat > "$tmpfile"; \
     gh attestation verify --repo=binary-install/binstaller --cert-identity-regex='.github/workflows/generate-installer.yml@refs/heads/main' "$tmpfile" && \
     sh "$tmpfile" $VERSION; rm -f "$tmpfile")

GitHub Actions

- uses: actionutils/trusted-tag-verifier@v0
  with:
    verify: 'binary-install/setup-x@v1'

- name: Install binstaller
  uses: binary-install/setup-x@v1
  with:
    script_url: https://github.com/binary-install/binstaller/releases/latest/download/install.sh
    gh_attestations_verify_flags: --repo=binary-install/binstaller --signer-workflow=actionutils/trusted-go-releaser/.github/workflows/trusted-release-workflow.yml

Go Install

# Latest version
go install github.com/binary-install/binstaller/cmd/binst@latest

# Specific version
go install github.com/binary-install/binstaller/cmd/binst@v0.1.0

🚀 Quick Start

Basic Usage

The workflow in action:

# Step 1: Initialize configuration from a source
binst init --source=github --repo=owner/repo -o .binstaller.yml

# Step 2 (Optional): Embed checksums for enhanced security
binst embed-checksums --config .binstaller.yml --version v1.0.0 --mode download

# Step 3: Generate installation script
binst gen -o install.sh

# Or without embedded checksums
binst init --source=goreleaser --file=.goreleaser.yml | binst gen > install.sh

📖 Usage Examples

From GoReleaser Configuration

# Step 1: Extract config from GoReleaser YAML
binst init --source=goreleaser --file=.goreleaser.yml -o .binstaller.yml

# Step 2 (Optional): Embed checksums for enhanced security
binst embed-checksums --config .binstaller.yml --version v1.0.0 --mode download

# Step 3: Generate installer script
binst gen --config=.binstaller.yml -o install.sh

From GitHub Repository

# Step 1: Auto-detect from GitHub releases API
binst init --source=github --repo=junegunn/fzf -o fzf.binstaller.yml

# Step 2 (Optional): Embed checksums for enhanced security
binst embed-checksums --config fzf.binstaller.yml --version 0.44.1 --mode download

# Step 3: Generate installer
binst gen --config=fzf.binstaller.yml -o fzf-install.sh

From Aqua Registry

Use configurations from Aqua's standard registry to initialize binstaller config:

# Step 1: Initialize from Aqua's standard registry configuration
binst init --source=aqua --repo=junegunn/fzf -o fzf.binstaller.yml

# Step 2 (Optional): Embed checksums for enhanced security
binst embed-checksums --config fzf.binstaller.yml --version 0.44.1 --mode download

# Step 3: Generate installer
binst gen --config=fzf.binstaller.yml -o fzf-install.sh

Manual Configuration

# Step 1: Create or edit .binstaller.yml manually
vim .binstaller.yml

# Step 2 (Optional): Embed checksums for enhanced security
binst embed-checksums --config .binstaller.yml --version v1.0.0 --mode download

# Step 3: Generate installer script
binst gen -o install.sh

⚙️ Configuration Format

The .binstaller.yml configuration file uses a simple, declarative format:

schema: v1
name: fzf
repo: junegunn/fzf
default_version: latest
asset:
  template: ${NAME}-${VERSION}-${OS}_${ARCH}${EXT}
  default_extension: .tar.gz
  rules:
    - when:
        os: windows
      ext: .zip
checksums:
  template: ${NAME}_${VERSION}_checksums.txt
  algorithm: sha256
supported_platforms:
  - os: linux
    arch: amd64
  - os: darwin
    arch: amd64
  - os: windows
    arch: amd64

🔧 Advanced Features

Security Features

• Embedded Checksums: Use binst embed-checksums to embed checksums directly into the configuration for enhanced security
• Automatic Verification: When checksums are embedded, downloaded binaries are automatically verified
• Reproducible Scripts: Generated scripts are deterministic and traceable
• Flexible Security: Choose between external checksum files or embedded checksums based on your needs

CI/CD Integration

Perfect for CI/CD pipelines where you need fast, reliable binary installations:

# GitHub Actions example
- name: Install tool
  run: |
    curl -sfL https://raw.githubusercontent.com/your-org/your-tool/main/install.sh | sh
    echo "./bin" >> $GITHUB_PATH

🎯 Why binstaller?

binstaller provides a modern, secure approach to binary installation:

• Universal Support: Unlike tools focused only on Go, works with any static binary on GitHub
• Enhanced Security: Embedded checksums provide better security than traditional approaches
• Flexible Configuration: YAML-based configuration is more maintainable than command-line flags

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Original GoDownloader project by the GoReleaser team
• Aqua project for package management inspiration
• All contributors who have helped improve this project

🐦️ Author

	haya14busa