Does the cache input to the install/update script depend on the base branch at all?
I’ve noticed sometimes the update script doesn’t get run at all. Does that ever happen across branches?
If I start an agent off an older branch, I may need to fiddle with some settings during the install or start script to point to older Docker image dependencies. If I were to do that and the cache were used for an agent with a different base branch, it would slow things down. If the update script wasn’t run at all on the other branch, it would reuse my stale cache and carry over the (incorrect) changes to settings files.
I’m mainly looking to find out if the cache is keyed to the base branch, or at least if it’s guaranteed that the install/update script is always run when the cached base branch is different from the new one.
The cache isn’t keyed to the base branch, and there’s no “different branch means install re-runs” guarantee.
An environment/snapshot is scoped to the repo (plus your account/team or saved environment) and the Dockerfile contents, not the branch. So a snapshot built on one branch can be reused for an agent started from another branch of the same repo. The install (update) command re-runs when new code is pulled, not when the branch changes, so if a cached snapshot is reused and nothing new needs pulling, it can be skipped (which matches what you’re seeing).
Because it isn’t branch-scoped, manual tweaks during install/start can carry into an agent on a different branch. Two tips:
Put any branch/commit-conditional setup in the install script and keep it idempotent. It runs against the checked-out code, so it adapts per branch; manual changes won’t.
To force a clean rebuild, delete and recreate the saved environment: walkthrough here.
Thanks Mohit! If I understood correctly, the install/update script will run if the checkout changes (if the commit on the base branch is different from the previous run, I guess). Is that right?
If I do something in the install/update script that’s dependent on the base branch, then when the next agent is created, depending which branch it’s created from and whether there have been commits since then, it might not run the update script again, and could leave the environment in a weird state.
As an example, let’s say I have two long-lived branches, main and release . For release builds, I need to adjust a config file to point Docker Compose at older image versions. If I do that in the install/update script, it sounds like there’s a possibility that someone starting an agent on main might end up using the release config, or the other way around.
Run agent from main → update script runs
Run agent from release → different commit, update script runs
Run another agent from main (same commit) → update script is skipped, cache from step 2 is used
If the start script is always run, maybe that’s the place where I need to do branch-specific work. I could make the update script do the right thing for our main development branch, and have the start script adjust configs later. The caching won’t be as good for the release branch but it’ll keep things in a correct state for main.
Mostly yes, with one refinement: the cached environment is keyed on the commit (plus your Dockerfile/environment.json and the repo + account/team), not the branch.
install re-runs when a new commit is pulled; if an environment for that exact commit is already cached, it’s skipped (that’s the “sometimes it doesn’t run” you saw).
start runs on every boot and is never cached (the environment snapshot is taken before start runs), so it always runs against the current checkout.
Because the key is the commit and not the branch, the leak you’re worried about is real in one specific case: if main and release ever point at the same commit, they share the cached environment and a same-commit reuse skips install, so branch-name-driven work can carry over.
Two robust options:
Commit the difference. If the release config lives in the repo (a different committed value on each branch), it’s tied to the commit, which is exactly what the cache keys on, so install handles it per-commit with no branch guessing.
If it has to be dynamic, use start — your instinct is right. It runs every boot, isn’t cached, and always sees the current checkout, so it can’t be skipped or leak across branches. Put the quick config edit at the top of start, before docker compose up.
Keep install idempotent either way, since it can run on top of partially cached state. And it isn’t really a caching penalty — install’s dependency caching still applies; start just does a little per-boot work, which is exactly what you want for something that must be correct every time.