Skip to content
ocx
install

Catch a forgotten lock in CI

Editing ocx.toml by hand, Node.js 24 to 26, leaves ocx.lock behind. ocx lock --check fails the CI job with exit 65 and says to run ocx lock; ocx lock writes the new digests and the check passes.

Duration

Transcript

Node 26 became a long-term support release in October, and the repository still pins 24.

Here is what happens when someone moves that pin by hand and forgets the lock.

The pin in ocx.toml says 24.

ocx upgrade with the major flag would move the pin and the lock in one step.

Instead, a teammate edits the line by hand, from 24 to 26.

Nobody runs ocx lock afterwards, so the lock still records the Node 24 builds.

ocx lock with the check flag reads both files and compares them.

They no longer agree, so it exits 65, and the message ends with the fix.

Exit 0 means the lock is current, and 78 means there is no lock at all.

What exactly does the check compare?

The lock stores a hash of what ocx.toml declares.

The check hashes those declarations again and compares the two.

A comment declares nothing, so the check still passes.

A new tag changes the hash, and the check fails.

It resolves nothing, writes nothing and makes no network call.

Without the check, the job would still stop.

ocx exec, env and pull each refuse a stale lock, with the same exit 65.

None of them runs Node, old or new, until the two files agree.

The check just names the problem first, in a step of its own.

The fix is the one the message names.

ocx lock resolves the new tag and writes the Node 26 digests.

The check now exits 0.

And ocx exec runs Node 26.

The new lock goes into the same commit as the edited pin.

In CI, make the check the first OCX command of the job.

It needs no network, so a stale lock fails before any tool is downloaded.

Then ocx env with the CI flag puts the locked tools on the PATH for later steps.

From there on, every step is a plain command.

Add the check to your own CI, then edit a pin by hand and watch it catch the change.

The installer and the CI guides are at ocx.sh.

Next: one project that needs two Node versions at the same time.

Embed this video

HTML

<div style="aspect-ratio:16/9"><iframe src="https://ocx.sh/learn/videos/02-lock-check/embed/" title="Catch a forgotten lock in CI" loading="lazy" allow="fullscreen" style="width:100%;height:100%;border:0"></iframe></div>

MDX or JSX

<div style={{aspectRatio: '16/9'}}><iframe src="https://ocx.sh/learn/videos/02-lock-check/embed/" title="Catch a forgotten lock in CI" loading="lazy" allow="fullscreen" style={{width: '100%', height: '100%', border: 0}}></iframe></div>

README Markdown

[![Catch a forgotten lock in CI](https://ocx.sh/learn/videos/02-lock-check/light/poster.jpg)](https://ocx.sh/learn/videos/02-lock-check/)

Duration

Transcript

This is Rexy. Rexy writes code on a Mac.

Rexy: It's one line. I'll edit it.

Rexy: Done! Pushed.

Steggo builds the same project in CI.

CI checks the lock first. Exit 65: the two files disagree.

Pecky: I'm Pecky the dinosaur!

Pecky: Red means stop!

Rexy has a problem.

What can he do?

Rexy: I changed one line!

Rexy: Which file is right?

Bronto: Both. ocx.toml says what you want.

Bronto: ocx.lock says what you get.

ocx.lock keeps one exact digest per platform.

Rexy: Oh no. I forgot the lock.

Bronto: Read the end: run ocx lock Rexy: On it!

ocx lock resolves :26 and writes the new digest.

Same check, after ocx lock Steggo: Green!

Exit 0: the lock matches ocx.toml again.

CI runs Node.js 26.13.0 now.

Commit ocx.toml and ocx.lock together.

Check the lock in CI. Fix it with ocx lock

Embed this video

HTML

<div style="aspect-ratio:16/9"><iframe src="https://ocx.sh/learn/videos/02-lock-check/dino/embed/" title="Catch a forgotten lock in CI" loading="lazy" allow="fullscreen" style="width:100%;height:100%;border:0"></iframe></div>

MDX or JSX

<div style={{aspectRatio: '16/9'}}><iframe src="https://ocx.sh/learn/videos/02-lock-check/dino/embed/" title="Catch a forgotten lock in CI" loading="lazy" allow="fullscreen" style={{width: '100%', height: '100%', border: 0}}></iframe></div>

README Markdown

[![Catch a forgotten lock in CI](https://ocx.sh/learn/videos/02-lock-check/dino/poster.jpg)](https://ocx.sh/learn/videos/02-lock-check/#dino)