safe_sleep.sh: Problem that it is solving is not clearly defined, implementation contains busy wait

[logiclrd]

Why are you starting this discussion?

Question

What GitHub Actions topic or product is this about?

Actions Runner

Discussion Details

There is a script that is part of the actions/runner codebase called safe_sleep.sh. Looking at the history, it was originally added as a function inside run-helper.sh.template with no clear explanation, trying to use system commands sleep and ping before falling back on a busy wait, and then got refactored out to a separate file that was only the busy wait before later having a bug fix and then the alternatives readded.

This script is a significant code smell, in my estimation. Anything that resorts to doing a busy wait is extremely questionable. Also, the script's "shebang" specifies that it should be run with /bin/bash, and yet the script contains code that tests whether it is running in Bash. Furthermore, outside of that check, it contains bash-specific syntax for the busy wait.

To summarize:

• The file includes a test that it is running in Bash, implying that it is intended to work with non-Bash scripts. But, it also uses Bash-specific syntax that could only work on Bash.
• It is not obvious why there should ever be a need to busy wait.

It is hard to evaluate what workable changes are because it isn't clearly documented what platforms the script is expected to run on. But, given that it is part of Git Actions, it's a reasonable assumption, I think, that it is the range of supported operating systems, which is documented to be Windows, Mac OS X 11+ and a range of modern Linux distributions.

I believe this support range should be documented in the safe_sleep.sh file so that anybody working on it knows exactly what it is trying to support (specifically modern Linux distrubions and OS X 11+). Furthermore, where there are unusual cases that need to be handled, they should be explicitly called out.

Given this specific range, though, it seems to me that the script is fundamentally unnecessary, because all modern Linux distributions and OS X 11+ have /usr/bin/sleep to begin with. If there is, in fact, a supported environment that lacks /usr/bin/sleep, it needs to be documented in safe_sleep.sh (maybe there are chroot jails being set up that don't provide access to sleep??), and if there isn't, then safe_sleep.sh shouldn't exist and code should simply use /usr/bin/sleep (or, sleep wherever it is found on PATH).

[arthuRHD]

If you cancel a workflow, sleep doesn’t always exit immediately. (or maybe they just want to charge you more for CPU usage but shhhhh)

[logiclrd]

Do you mean that just using /usr/bin/sleep would cause problems with interrupting workflows? If so, then the current safe_sleep.sh should be affected by that because it does try to use /usr/bin/sleep if it is present.

Or do you mean that the busy wait has problems with interrupting workflows? If so, then all the more reason to get rid of any potential busy wait -- but that means clearly identifying and documenting the scenarios that currently fall back on it.

[arthuRHD]

I have seen an article on the subject if you want to dive in:

The Curious Case of safe_sleep.sh in GitHub Actions Runner | by Navaneeth Sen | Medium https://share.google/NI4FSbLs00JtSvUxU

[logiclrd]

Interesting -- so it used to be even worse than it is now!

[logiclrd]

I went off to see what else I could find, and found this:

https://lobste.rs/s/l4rowa/github_actions_safe_sleep_sh

One of the comments at the bottom of that discussion conjectures that they were using Ubuntu on a pre-release WSL 1.0 in 2019, a time when WSL had a bug that made its sleep syscall non-functional.

There's no explanation for why the original implementation got replaced with a shoddily-written busy wait, though.

Anyway, that all predates the state I'm commenting on in this discussion.

[logiclrd]

Also found another article:

https://www.theregister.com/2025/12/02/zig_quits_github_microsoft_ai_obsession/

Apparently Zig did indeed decide they'd had too much and dropped GitHub, and safe_sleep.sh was one of the major instigators. Another, if I've understood correctly, was that the job scheduler switched from a FIFO scheme to apparently random scheduling, and for them, that meant that sometimes commits to main would not get built for a really long time.

[github-actions[bot]]

🕒 Discussion Activity Reminder 🕒

This Discussion has been labeled as dormant by an automated system for having no activity in the last 60 days. Please consider one the following actions:

1️⃣ Close as Out of Date: If the topic is no longer relevant, close the Discussion as out of date at the bottom of the page.

2️⃣ Provide More Information: Share additional details or context — or let the community know if you've found a solution on your own.

3️⃣ Mark a Reply as Answer: If your question has been answered by a reply, mark the most helpful reply as the solution.

Note: This dormant notification will only apply to Discussions with the Question label. To learn more, see our recent announcement.

Thank you for helping bring this Discussion to a resolution! 💬

[logiclrd]

@ruvceskistefan @horner @TingluoHuang 👀

[Venu5198]

You’re right to call this out as a code smell, but the conclusion (“this script shouldn’t exist”) is too aggressive given how the runner operates in practice.

1. Why something like safe_sleep.sh exists

The runner does not execute exclusively in “clean, modern OS environments.” It frequently runs in:

• Minimal container images (scratch/alpine variants, stripped busybox setups)
• Ephemeral bootstrap environments during provisioning
• Self-hosted runners with unpredictable PATH/tooling
• Partially initialized systems where coreutils may not be available or stable

In these scenarios, even something as basic as sleep can be:

• Missing
• Shadowed by a broken implementation
• Interrupted or behaving inconsistently under signal handling

So the intent of safe_sleep.sh is not performance — it’s defensive determinism. The busy wait is a last-resort fallback to guarantee delay semantics when the environment is unreliable.

That said, the current implementation does a poor job of making this intent clear.

---

2. The real problems (you correctly identified)

You’re absolutely right on these points:

• Bash contradiction

  • Shebang enforces /bin/bash
  • Yet it checks whether it’s running in bash
  • And uses bash-specific syntax anyway
    → This is internally inconsistent and misleading

• Lack of documented constraints

  • No clear statement of:

    • Supported environments
    • Failure modes being guarded against
      → Makes it impossible to reason about necessity

• Busy wait opacity

  • No explanation of why fallback exists
  • No indication of when it is expected to trigger
    → Looks like accidental complexity instead of intentional resilience

---

3. Why simply “use /usr/bin/sleep” is not sufficient

This assumption only holds if you guarantee:

• Full OS userland is present
• PATH is sane
• No sandboxing/chroot limitations
• No broken symlinks or stripped binaries

The runner cannot safely assume those conditions.

So removing the script entirely would introduce non-deterministic failures in edge environments — the exact thing the runner tries to avoid.

---

4. What should actually be fixed (actionable)

Instead of removing the script, it should be made explicit, minimal, and consistent:

A. Document intent clearly at the top

Add something like:

# This script provides a resilient sleep mechanism for environments where:
# - `sleep` may not exist or may be unreliable
# - PATH may be incomplete or misconfigured
# - the runner is executing in minimal or bootstrap environments
#
# Busy-wait is used strictly as a last-resort fallback.

---

B. Remove the bash ambiguity

Pick one:

Option 1 (recommended): commit to bash

• Keep /bin/bash
• Remove the “are we in bash?” check
• Use bash features cleanly

Option 2: make it POSIX-compliant

• Switch to /bin/sh
• Remove bash-only syntax
• Ensure compatibility

Right now it does neither correctly.

---

C. Make fallback logic explicit and traceable

Example structure:

if command -v sleep >/dev/null 2>&1; then
    sleep "$1"
elif command -v ping >/dev/null 2>&1; then
    ping -c "$1" 127.0.0.1 >/dev/null 2>&1
else
    # last resort: busy wait
    start=$(date +%s)
    while [ $(($(date +%s) - start)) -lt "$1" ]; do :; done
fi

And log (even optionally) when fallback is used.

---

D. Define supported environments

Be explicit in comments:

• Linux (including minimal containers)
• macOS runners
• Self-hosted runners with unknown state

Call out that this is not about standard OS installs, but degraded environments.

---

5. Bottom line

• The script is justified, but poorly implemented and undocumented
• The busy wait is acceptable only as a last-resort fallback
• The real issue is lack of clarity and consistency, not existence

[logiclrd]

I figured this was the case. But in the absence of this documentation, the justification is invisible. If the script were removed and failures occurred, then it could be reintroduced with documentation of those exact failures. Of course, that sort of "probe the production environment" testing isn't going to fly 😂 But the points the LLM has outlined here are all good and pretty much cover all the bases.

[logiclrd]

Well, apart from the "coreutils may not even be stable" one, because if the probe for a command finds an unstable version, it's still going to try using it. 🙂

[github-actions[bot]]

🕒 Discussion Activity Reminder 🕒

This Discussion has been labeled as dormant by an automated system for having no activity in the last 60 days. Please consider one the following actions:

1️⃣ Close as Out of Date: If the topic is no longer relevant, close the Discussion as out of date at the bottom of the page.

2️⃣ Provide More Information: Share additional details or context — or let the community know if you've found a solution on your own.

3️⃣ Mark a Reply as Answer: If your question has been answered by a reply, mark the most helpful reply as the solution.

Note: This dormant notification will only apply to Discussions with the Question label. To learn more, see our recent announcement.

Thank you for helping bring this Discussion to a resolution! 💬

[SriSomanaath]

This is a fair critique of the runner's helper. The busy-wait exists because the script must remain interruptible by signals across shells where sleep alone doesn't reliably forward SIGTERM to the parent during graceful shutdown - a plain sleep would delay cancellation. A cleaner approach is read -t < <(:) or trapping the signal and breaking the loop, which avoids the spin. If you want this fixed upstream, the actions/runner repo is the right place to open an issue with a proposed patch - happy to help draft the trap-based version.

[dhanushkonduru]

I think the criticism is fair, but removing safe_sleep.sh outright feels a bit aggressive without knowing the runner scenarios it was meant to handle.
The real problem is not just the script itself, but the lack of documentation around why it exists and what environments it is supposed to support. The Bash check is also confusing, especially since the file already declares /bin/bash and uses Bash-specific syntax.
I would keep the fallback for now, but make its purpose explicit, document the supported environments, and treat the busy-wait as a true last-resort path. That would preserve reliability while making the code much easier to understand and maintain.

[logiclrd]

I created a PR with proposed changes 3 weeks ago:

actions/runner#4465

It doesn't appear to have gotten any traction at all so far.