### Summary `check_readme` fails with `Error: Missing 'Usage' header in file contents` for a `README.md` that has a `## Usage` header, once more of the file follows the header than the pipe between `echo` and `grep` can hold. The check pipes the whole file into `grep -q` ([`templates/readme-check.yml` lines 13 to 23](https://gitlab.com/components/toolkit/-/blob/80ea0b504c93437a36f8ed8292b19b35f34e4fd7/templates/readme-check.yml#L13-23)): ```shell file_contents=$(cat ./README.md) # ... if echo "$file_contents" | grep -q "^## $1"; then ``` `grep -q` exits as soon as it finds the header. If `echo` still has part of the file to write at that point, it is killed by `SIGPIPE`, and because the job runs with `pipefail` the pipeline's status is 141. The `if` takes the `else` branch and the job reports the header as missing. The job runs with `pipefail` on the Docker executor: - GitLab Runner starts the job container with `sh -c` and a script that runs the first `bash` or `sh` it finds ([`shells/bash.go` line 514](https://gitlab.com/gitlab-org/gitlab-runner/-/blob/a278fd0507debd103f90ce8a8c62ca4743a97a10/shells/bash.go#L514), script at [lines 21 to 38](https://gitlab.com/gitlab-org/gitlab-runner/-/blob/a278fd0507debd103f90ce8a8c62ca4743a97a10/shells/bash.go#L21-38)). The `busybox` image has no `bash`, so that is BusyBox `sh` (v1.38.0 in `busybox:latest` on 2026-10-12, `busybox@sha256:fd7dc98638c8e305f4dc34e979f1c0fdfdcaeb0fbf8fcff77ae834b6da3d7e6e`). - Before the job's script, the runner runs `case "$(set -o)" in *"pipefail"*) set -o pipefail;; esac; set -o errexit` ([`shells/bash.go` line 453](https://gitlab.com/gitlab-org/gitlab-runner/-/blob/a278fd0507debd103f90ce8a8c62ca4743a97a10/shells/bash.go#L453)), which turns `pipefail` on in any shell that has it, and BusyBox `sh` has it. Runners have done this since 14.9 (the `case` form replaced a `grep` in 19.1), so it is not a recent change. With the default 64 KiB pipes and `## Usage` near the top, a README larger than 69,632 bytes fails every time, one between 65,537 and 69,632 bytes fails some of the time, and one of 65,536 bytes or less passes. Where the pipes are smaller the limit is lower: with 8 KiB pipes, a README larger than 12,288 bytes fails every time. The measurements are below. ### Steps to reproduce Without GitLab, with the job's image and the option the runner sets: 1. Create a README with the headers at the top and about 88 KB of text after them: ```shell mkdir big-readme && cd big-readme { printf '# C\n\n## Usage\n\n## Contributing\n\n'; yes 'Filler line to make this README larger than a pipe buffer.' | head -n 1500; } > README.md wc -c README.md # 88532 ``` 1. Run the check's pipeline in `busybox` with `pipefail` on, and then with `grep` reading the file: ```shell docker run --rm -v "$PWD:/w:ro" -w /w busybox sh -c ' set -o pipefail file_contents=$(cat ./README.md) if echo "$file_contents" | grep -q "^## Usage"; then echo "found"; else echo "missing, pipeline status $?"; fi if grep -q "^## Usage" README.md; then echo "found when grep reads the file"; fi' ``` This prints `missing, pipeline status 141` and then `found when grep reads the file`. Without `set -o pipefail` the first check prints `found`. In a pipeline: 1. Include `readme-check` (or `all-jobs`) in a project whose `README.md` has `## Usage` and `## Contributing` near the top and is larger than 69,632 bytes. 1. Run the pipeline on a Linux runner with the Docker executor. 1. `check_readme` fails with `Error: Missing 'Usage' header in file contents`. ### Example Project I have not set one up on GitLab.com. The commands above reproduce it without a project, and the pipeline runs below were on a local instance. ### What is the current *bug* behavior? The job fails with `Error: Missing 'Usage' header in file contents` for a README that has the header. The message points at the README rather than at the check, so the author looks for a problem in a file that has none. ### What is the expected *correct* behavior? The check passes whenever the README has the headers it asks for, whatever the file's size, and fails only when a header is missing. ### Relevant logs and/or screenshots The job log for a 69,633-byte README on a local GitLab CE 19.4.1 with GitLab Runner 19.4.1 and the Docker executor: ```plaintext Using docker image sha256:aaef90e065235eb0b2d9938be85d1b81add2902cf89affe2cdfa19be33476ac0 for busybox with digest busybox@sha256:fd7dc98638c8e305f4dc34e979f1c0fdfdcaeb0fbf8fcff77ae834b6da3d7e6e ... $ ls README.md || (echo "Please add a README.md file for your component" && exit 1) README.md $ file_contents=$(cat ./README.md) $ # Shell script inline # collapsed multi-line command Error: Missing 'Usage' header in file contents ERROR: Job failed: exit code 1 ``` <details> <summary>Measurements</summary> I ran the job's own script, with the runner's shell detection and the lines it writes before and after the script, in `busybox@sha256:fd7dc98638c8e305f4dc34e979f1c0fdfdcaeb0fbf8fcff77ae834b6da3d7e6e`, with both headers in the first 60 bytes of the README: | README size (bytes) | Passed with 64 KiB pipes | Passed with 8 KiB pipes | |--------------------:|-------------------------:|------------------------:| | 1,000 | 20/20 | | | 8,192 | | 10/10 | | 12,288 | | 9/10 | | 12,289 | | 0/10 | | 65,536 | 20/20 | 0/10 | | 65,537 | 19/20 | | | 69,632 | 19/20 | | | 69,633 | 0/20 | | | 177,037 | 0/20 | | Linux gives a new pipe two pages (8 KiB) instead of sixteen when the user creating it already holds more than `fs.pipe-user-pages-soft` pages of pipe buffers and the process has neither `CAP_SYS_RESOURCE` nor `CAP_SYS_ADMIN`, which a default Docker container does not have (`alloc_pipe_info` in `fs/pipe.c`). The count is kept per user ID for the whole host, so root in a job container shares it with every other root process on the runner host. For the 8 KiB column I ran the job under a user ID that another container already held enough pipe buffers for, which gave 8 KiB pipes without changing the host's settings. I also ran the component at 80ea0b504c93437a36f8ed8292b19b35f34e4fd7 on the local GitLab, with this project's own `README.md` (`## Usage` at byte 157, `## Contributing` at byte 7,475) padded at the end and a `.gitlab-ci.yml` that includes only `readme-check`: | README | Passed | |-------------------------|-------:| | 7,591 bytes (unchanged) | 5/5 | | 65,536 bytes | 2/5 | | 69,633 bytes | 0/5 | | 100,000 bytes | 0/5 | The 65,536-byte README failed more often there than the 64 KiB column above shows for that size. That fits smaller pipes on that host during some of those runs, but I did not measure the pipe size during them. </details> ### Output of checks Not specific to an instance: the failure comes from the job's script and the runner's shell options. The runs above used GitLab CE 19.4.1 and GitLab Runner 19.4.1. ### Possible fixes Let `grep` read the file itself, so there is no pipe and no writer to kill: ```shell if grep -q "^## $1" README.md; then ``` and drop the `file_contents=$(cat ./README.md)` step, which nothing else reads. With that change on the same local GitLab, a 100,000-byte README passed 4 of 4 runs, and a README without `## Usage` still failed 4 of 4 with `Error: Missing 'Usage' header in file contents`. GitLab Runner fixed the same pattern in its own script by replacing a `head -n1` that read from a pipe (gitlab-org/gitlab-runner@7c4c1fc64471516235c461b538b3a36715e945c2). This is the only check in the templates that pipes into a command that can stop reading before its input ends. !25, which I opened for #6, turns the same `check_header` function into a loop over several header names, and the same change applies inside that loop. I'd like to work on this.