Treat a notebook run in CI as running a script from whoever last edited it. Use a throwaway runner, a least privilege token, no production credentials, a timeout per cell, and run only notebooks from branches you trust. Review changed notebooks as code first.
What nbconvert execute does
The nbconvert documentation says it can execute the input cells of an ipynb file and save the results, with input and output cells, as an ipynb file. The command line form adds an execute flag to the convert command. The docs suggest uses such as running all notebooks in a library in one step, or automating analysis across several notebooks.
Cells run in a kernel. The kernel is a program that runs the code, and it has whatever access the CI job has.
Settings worth knowing
The documentation describes an ExecutePreprocessor with a timeout setting, the maximum seconds each cell may run, with a default of 30 seconds, and a kernel name option. Both can be set on the command line.
jupyter nbconvert --ExecutePreprocessor.timeout=600 --to notebook --execute analysis.ipynb
A timeout limits runaway cells. It does not limit what a cell does in that time.
A checklist
| Control | Why |
|---|---|
| Ephemeral runner | Nothing persists between runs |
| Minimal job token | A cell can use any token in its environment |
| No production secrets in the job | Use test data and test credentials |
| Pinned environment from a lock file | The notebook cannot pull arbitrary packages unnoticed |
| Network egress limits where possible | Cells can send data out |
| Per cell timeout | Stops hangs and some abuse |
| Pull requests from forks run without secrets | Outsiders must not run code with your credentials |
Review the notebook first
A notebook diff is hard to read. Before CI executes a changed notebook:
- Convert it to a script or diff its source cells, ignoring outputs.
- Look for shell commands, network calls and install commands.
- Check that no output cell contains keys, as covered in /resources/blog/clean-notebook-outputs-before-you-commit.
- Require approval before running notebooks changed by new contributors.
What a failed run tells you
A notebook that fails in CI is useful evidence. If a cell errors on a missing package, the environment file is incomplete. If it errors on a network call, the notebook depends on something outside the repository. Record both as findings, and fix the notebook or the environment, not the CI job's permissions.
Parameterized runs
If you pass parameters into notebooks, remember that parameters become code. See /resources/blog/what-does-papermill-run-when-you-parameterize-a-notebook for what that tool does.
Where Safeguard fits
Safeguard's policies and gates can block a pull request that adds a vulnerable dependency to the environment your notebooks use. Try it with the free scan at gold.safeguard.sh/scan.
Try it yourself
Click through it at your own pace, or open it full screen. Watch how a change is checked before it can merge.
Quick check
Does the cell timeout make execution safe?
No. It only caps how long each cell may run.
Should fork pull requests run notebooks with your secrets?
No. Run them without secrets, or require review first.
Sources
- Executing notebooks, nbconvert documentation, fetched 19 October 2026.
Last reviewed: 19 October 2026.
