feat: add override-overlay
Metadata
Current evaluation
Merged override-overlay, enabling scriptlets to run in a chroot. Adds grammar support, mutual exclusivity with overlay-script, chroot mountpoints, layer hashing, and tests. Approved and passed CI.
Suggested action: —
No scores available.
Issue body
- [ x] Have you followed the guidelines for contributing?
- [ x] Have you signed the [CLA](http://www.ubuntu.com/legal/contributors/)?
- [x ] Have you successfully run `make lint && make test`?
- [ ] Have you added an entry to the changelog (`docs/reference/changelog.rst`)?
---
**Summary of Changes**
This PR introduces the new override-overlay feature, enabling execution of an overlay scriptlet inside a chrooted environment as an alternative to the existing overlay-script mechanism.
**Key Updates**
Grammar: Added override-overlay keyword.
Validation: Added schema validation ensuring override-overlay is mutually exclusive with overlay-script.
**Execution logic:**
When override-overlay is set, run the scriptlet from within a minimal chroot.
Added necessary mountpoints (/usr, /bin, /lib64, /lib) to support chroot execution.
Hashing: Included override-overlay in layer hashing to ensure proper rebuild triggers.
Tests: Updated marshalling/unmarshalling tests to include the new field when not setted.
**Impact**
This feature expands overlay customization capabilities while preserving backwards compatibility. Standard overlay-script continues to function normally when override-overlay is not provided.
**Testing**
I tested the feature using the following parts.yaml, which exercises the override-overlay scriptlet inside the chroot and verifies environment behavior through proof.txt, using : python -m craft_parts --overlay-base <basedir> [clean]
```
parts:
hello:
plugin: nil
source: hello.sh
source-type: file
#overlay-script: |
override-overlay: |
echo "==== CHROOT TEST ===" > proof.txt
echo "PWD: $(pwd)" >> proof.txt
echo "result of : ls -l ." >> proof.txt
ls -l . >> proof.txt
readlink -f / >> proof.txt
override-build: |
cp hello.sh "${CRAFT_PART_INSTALL}/hello"
chmod +x "${CRAFT_PART_INSTALL}/hello"
stage:
- "*"
prime:
- "*"
```
Evaluation history
| Date | Model | Scores | Action | Summary |
|---|---|---|---|---|
| qwen/qwen3.6-35b-a3b | — | — | Merged override-overlay, enabling scriptlets to run in a chroot. Adds grammar support, mutual exclusivity with overlay-script, chroot mountpoints, layer hashing, and tests. Approved and passed CI. | |
| qwen3.6-35b-a3b-mtp-q6 | — | — | Merged the override-overlay feature, allowing overlay scriptlets to execute within a chroot environment. Implementation includes schema validation, required mountpoints, layer hashing, and tests, preserving backward compatibility with overlay-script. |
Update history
No update history recorded yet.
Related issues
| Issue | Project | State | Summary | Similarity |
|---|---|---|---|---|
| #1472 feat: add override-overlay | craft-parts | merged | Merged the override-overlay feature. Approved by two reviewers with 180 additions and 35 deletions across 10 files. Passed required CI checks and was successfully integrated into the codebase. | |
| #299 feat: enable override-overlay | imagecraft | merged | Merged following approval from two reviewers and passing CI checks. Updated craft-parts to ~2.30 to enable override-overlay support and added a corresponding spread test. | |
| #1165 feat: enable override-overlay | rockcraft | merged | Merged. Updates craft-parts to enable the override-overlay key, replaces overlay-script in tests, and updates documentation. Reviewers approved the changes and confirmed upgrading sphinx-terminal resolves linting errors. All required checks passed before merge. | |
| #1567 feat(overlay): plugins can define overlay commands | craft-parts | merged | Merged PR enabling plugins to define overlay commands that execute inside the overlay chroot. Introduces override-overlay support with craftctl default signaling, mutually exclusive with overlay-script. Resolves CRAFT-5027. | |
| #134 overlay: add overlay package install (CRAFT-81) | craft-parts | merged | Merged. Adds overlay package installation by executing maintainer scripts in a chrooted environment to correctly update the package database. Approved by two reviewers, with clarifications added on pychroot usage and empty file safety. |