Skip to content

feat(ruby): add Alpine Linux (musl libc) support for x86_64 and aarch64 - #143

Merged
prateek-kumar-improving merged 13 commits into
mainfrom
musl-support-new
Jul 14, 2026
Merged

prateek-kumar-improving merged 13 commits into
mainfrom
musl-support-new

Conversation

@prateek-kumar-improving

@prateek-kumar-improving prateek-kumar-improving commented Jul 8, 2026

Copy link
Copy Markdown
Collaborator

Summary

Add Alpine Linux (musl libc) support for the valkey-rb gem on both x86_64 and aarch64 architectures. This enables users running Docker containers based on Alpine to use the gem with
prebuilt native libraries.

Issue link

This Pull Request is linked to issue: #98

Features / Behaviour Changes

  • The gem now automatically detects musl libc at runtime and loads the correct native library (*-unknown-linux-musl vs *-unknown-linux-gnu)
  • Alpine Linux 3.18+ is now a supported platform for both x86_64 and aarch64
  • CI validates the gem on Alpine Linux with full test coverage (standalone, TLS, cluster)
  • CD builds and publishes musl-compatible native libraries alongside glibc ones

Implementation

Runtime detection (lib/valkey/bindings.rb):

  • Added musl_libc? class method with a 3-check cascade:
    1. RUBY_PLATFORM contains "musl"
    2. /etc/alpine-release file exists
    3. RbConfig::CONFIG["target_os"] contains "musl"
  • platform_info now resolves {arch}-unknown-linux-musl when musl is detected

Build matrix (.github/json_matrices/build-matrix.json):

  • Added x86_64-unknown-linux-musl and aarch64-unknown-linux-musl target entries

CI workflow (.github/workflows/CI.yml):

  • Excluded musl targets from the regular glibc-based build/test jobs
  • Added dedicated build-and-test-musl job running natively inside ruby:3.3-alpine container on x64
  • Builds Rust FFI library with RUSTFLAGS="-C target-feature=-crt-static" (required for dynamic linking on musl)
  • Runs full test suite including standalone, TLS, and cluster

CD workflow (.github/workflows/cd.yml):

  • Added musl cross-compilation steps (musl-tools, rustup target, conditional --target flag)
  • Adjusted artifact upload paths for target-specific Cargo output directory
  • Added test-gem-musl job to verify the published gem loads and passes tests on Alpine

Test fix (test/valkey/uri_connection_test.rb):

  • Skip test_ssl_with_unreadable_file when running as root (Alpine CI container), since root bypasses file permission checks

Limitations

  • ARM64 (aarch64) musl is built via cross-compilation in CD but cannot be integration-tested in CI containers due to a [GitHub Actions limitation](https://github.blog/changelog/2025-
    09-19-deprecation-of-node-20-on-github-actions-runners/) where JavaScript-based actions don't work in Alpine containers on ARM64 runners. The x64 musl path has full integration
    testing.
  • Only Alpine Linux 3.18+ is tested; other musl-based distros (e.g., Void Linux) should work but are untested.

Testing

  • Full standalone, TLS, and cluster test suites pass on Alpine Linux (x86_64)
  • Semgrep security scanning passes (actions pinned to commit SHAs, no curl-pipe-shell)
  • Existing glibc and macOS test suites unaffected

Checklist

  • This Pull Request is related to one issue.
  • Commit message has a detailed description of what changed and why.
  • Tests are added or updated.
  • CHANGELOG.md and documentation files are updated.
  • Linters have been run (bundle exec rubocop) and pass.
  • Destination branch is correct - main
  • Create merge commit if merging release branch into main, squash otherwise.
  • Make sure to update the documentation in the valkey-glide-docs repository if necessary

Signed-off-by: Prateek Kumar <prateek.kumar@improving.com>
Signed-off-by: Prateek Kumar <prateek.kumar@improving.com>
…grep

Signed-off-by: Prateek Kumar <prateek.kumar@improving.com>
@prateek-kumar-improving
prateek-kumar-improving marked this pull request as ready for review July 8, 2026 18:57
Signed-off-by: Prateek Kumar <prateek.kumar@improving.com>
Comment thread lib/valkey/bindings.rb
@yipin-chen
yipin-chen requested a review from alexr-bq July 9, 2026 23:13
@alexr-bq

alexr-bq commented Jul 9, 2026

Copy link
Copy Markdown
Collaborator

Have you ran the CD workflow (in non-publish / dry-run mode) and validated it?

Comment thread .github/workflows/CI.yml Fixed
Signed-off-by: Prateek Kumar <prateek.kumar@improving.com>
Signed-off-by: Prateek Kumar <prateek.kumar@improving.com>
Signed-off-by: Prateek Kumar <prateek.kumar@improving.com>
Signed-off-by: Prateek Kumar <prateek.kumar@improving.com>
Signed-off-by: Prateek Kumar <prateek.kumar@improving.com>
Signed-off-by: Prateek Kumar <prateek.kumar@improving.com>
@prateek-kumar-improving

Copy link
Copy Markdown
Collaborator Author

Have you ran the CD workflow (in non-publish / dry-run mode) and validated it?

The CD workflow worked: https://github.com/valkey-io/valkey-glide-ruby/actions/runs/29279904222

Signed-off-by: Prateek Kumar <prateek.kumar@improving.com>
@prateek-kumar-improving

Copy link
Copy Markdown
Collaborator Author

CD workflow works after the last code change: https://github.com/valkey-io/valkey-glide-ruby/actions/runs/29351834655

@prateek-kumar-improving
prateek-kumar-improving merged commit 40c3e93 into main Jul 14, 2026
33 checks passed
@prateek-kumar-improving
prateek-kumar-improving deleted the musl-support-new branch July 14, 2026 17:06
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants