Pantry Redis services

Stacks consumes Redis through Pantry v0.10.43 at immutable commit c5e15260ccde34206082756a14d03e30cf1d7d5e. This page distinguishes Pantry's native project service from its ephemeral GitHub Actions service. They share package resolution and health semantics, but they do not share process state or persistence policy.

Evidence boundary

The lock, copied sources, and verification commands are retained in evidence/pantry/evidence.lock.json.

GitHub Actions contract

Use the Pantry Action when a job needs an isolated Redis process:

- name: Setup Pantry and Redis
  id: pantry
  uses: pantry-pm/pantry/packages/action@c5e15260ccde34206082756a14d03e30cf1d7d5e
  with:
    version: '0.10.43'
    install: 'false'
    services: redis@8.8.0

Both pins are intentional. The uses revision fixes the Action source, while version fixes the downloaded native Pantry CLI. services accepts an exact redis@X.Y.Z version; ranges and ambiguous versions fail before installation. The Action currently supports Redis services on Linux and macOS. Windows support is tracked upstream in Pantry issue 211 and is not implied by the cross-platform CLI installation contract.

Lifecycle sequence

1. Parse and deduplicate service declarations. Conflicting package and service versions fail before any process is started.
2. Install Redis through the native Pantry resolver with --no-save. This preserves package dependencies, integrity verification, platform selection, and Pantry's normal installation boundary without mutating the project manifest.
3. Resolve redis-server and redis-cli from the job-local pantry/.bin. A system Redis installation is not accepted as evidence for the requested pin.
4. Create an isolated directory under RUNNER_TEMP/pantry-services/redis.
5. Launch Redis on 127.0.0.1:6379 with protected mode enabled, persistence disabled, and explicit PID and log files. The service is not exposed on an external runner interface.
6. Wait up to 10 seconds for a valid, live daemon PID. PID creation is polled to avoid racing Redis daemonization.
7. Wait up to 30 seconds for redis-cli ping to succeed.
8. Read the running binary's version and reject it when it differs from the exact requested version.
9. Export REDIS_URL=redis://127.0.0.1:6379/0 and REDIS_SERVICE_VERSION; publish the same values as redis-url and redis-version Action outputs.
10. In the post step, issue SHUTDOWN NOSAVE only when this Action recorded a successful start.

Failure and diagnostic semantics

The setup step fails when installation fails, the installed binaries are missing, the PID is invalid or absent, Redis cannot answer a health check, or the running version differs from the exact request. PID-readiness errors include the Redis startup logfile, making port collisions, linkage failures, and invalid launch configuration visible in the Actions log. A failed setup never converts to a memory-backed cache or queue pass.

An immutable tag can become visible before GitHub finishes publishing its release assets. The Action retries only publication-shaped download failures, including 404, timeout, rate-limit, and server responses, with bounded capped backoff. Authorization and malformed-request failures remain immediate. Exhaustion names the requested release, platform, and attempt count instead of silently selecting another Pantry version.

An exact Actions cache hit may restore Pantry artifacts, but the Action still validates and starts the declared service. Restore-key matches are not treated as exact dependency state. When install: 'false' is combined with a service, project JavaScript dependencies remain untouched; only the runtime and explicitly requested service packages are provisioned.

Native project service contract

pantry start redis and pantry restart redis use the invoking project as the service scope. The service identifier, data directory, logs, and process state are project-specific, preventing one checkout from silently adopting another checkout's Redis process. Pantry uses its own installed redis-server and redis-cli, waits for PONG, and stops a failed start before returning an error. Restart preserves the same project scope.

Native project services are development infrastructure and may use persistent project data. The Action service is deliberately ephemeral and disables persistence. Tests and deployment tooling must not assume those two modes have the same durability or recovery behavior.

Consumer checks

A consuming workflow should verify both exported state and a real round trip:

test "$REDIS_URL" = "redis://127.0.0.1:6379/0"
test "$REDIS_SERVICE_VERSION" = "8.8.0"
test "$(redis-cli -u "$REDIS_URL" ping)" = "PONG"
redis-cli -u "$REDIS_URL" set contract-check ready
test "$(redis-cli -u "$REDIS_URL" get contract-check)" = "ready"

Stacks additionally retains cache and queue driver tests against the live URL. Service availability alone does not prove either driver contract.

Verification retained for this snapshot