Valkey vs Redis client compatibility in CI

By Kaveh Alemi·Latchkey

Valkey is a fork of Redis and speaks the same RESP protocol, so redis-cli, redis-py, and ioredis connect to it unchanged. Problems in CI come from the image name and version reporting, not the wire protocol: use the valkey image and expect a Valkey version string in INFO.

What this error means

A pipeline that switched the service from Redis to Valkey fails on an image pull (redis:7 vs valkey/valkey:8) or on a version assertion that checks redis_version but sees a Valkey version.

Error response from daemon: pull access denied for valkey, repository does
not exist or may require 'docker login'
# or a test asserting on:
server_name:valkey  valkey_version:8.0.1

Common causes

Wrong image reference for Valkey

Valkey is published under valkey/valkey, not the redis name, so a bare valkey image reference fails to pull.

Version checks that assume Redis

INFO reports server_name:valkey and a valkey_version; assertions hard-coded to redis_version misread it.

How to fix it

Use the valkey image and connect normally

1. Point the service at valkey/valkey with a real tag.
2. Connect with the same client and URL you used for Redis.
3. Relax version assertions to accept Valkey, or drop them.

services:
  cache:
    image: valkey/valkey:8
    ports: ['6379:6379']
    options: --health-cmd "valkey-cli ping" --health-retries 10

Ping with the matching CLI

The Valkey image ships valkey-cli; redis-cli also works against it since the protocol is shared.

valkey-cli -h localhost -p 6379 ping   # PONG

How to prevent it

• Reference valkey/valkey with an explicit tag, not a bare name.
• Avoid assertions that pin the exact server name/version across the fork.
• Keep the connection code identical since RESP is shared.

Frequently asked questions

Related guides

References

• GitHub Actions documentation