Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
37 changes: 37 additions & 0 deletions .github/workflows/github-actions-claude-shell-test.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,37 @@
name: Test Claude Docker scripts

on:
push:
branches: [master]
paths: &claude_paths
- 'claude.sh'
- 'env.sh'
- 'docker/*claude*.sh'
- '.github/workflows/github-actions-claude-shell-test.yml'
pull_request:
paths: *claude_paths

permissions:
contents: read

jobs:
shell-tests:
# The Git fixture creates /workspace and /home/claude-user on a fresh VM.
runs-on: ubuntu-26.04
timeout-minutes: 10
steps:
- name: Check out repository
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false
- name: Test wrapper arguments
run: bash docker/test-claude-sh.sh
- name: Pull container test image
run: docker pull openroad/flow-ubuntu26.04-dev:latest
- name: Test entrypoint account and settings
run: bash docker/test-claude-entrypoint.sh
- name: Test Git with reserved host paths
run: |
sudo mkdir /workspace /home/claude-user
sudo chown "$(id -u):$(id -g)" /workspace /home/claude-user
bash docker/test-claude-worktree-paths.sh
74 changes: 50 additions & 24 deletions claude.sh
Original file line number Diff line number Diff line change
Expand Up @@ -86,9 +86,8 @@ CONTAINER_HOME="/home/claude-user"

# --- Git data of a worktree ---
# A worktree's .git file, and the .git files of its submodules, point to the
# main checkout's git directory by host path, absolute or relative. Mount that
# directory and the worktree at their host paths, and start in the worktree's
# host path, so these links resolve in the container. /workspace stays.
# main checkout's git directory by absolute or relative paths. Keep their
# relative layout so links from submodules resolve in the container.
HOST_DIR=$(cd "${SCRIPT_DIR}" && pwd -P)
CONTAINER_WORKDIR=/workspace
GIT_TOP=""
Expand All @@ -106,21 +105,37 @@ outside_container_paths() {
}

GIT_MOUNTS=()
GIT_LINK_DIR=""
mount_prefix=""
# The existing checkout mount already preserves an exact /workspace path.
if { [[ "${HOST_DIR}" != /workspace ]] && ! outside_container_paths "${HOST_DIR}"; } ||
! outside_container_paths "${GIT_COMMON_DIR}"; then
mount_prefix=/tmp/claude-worktree
fi

# Only for the top of a checkout: a plain folder inside another repository
# must not get that repository's .git.
# must not get that repository's .git. A gitfile also needs relocation when
# it points inside the checkout but the /workspace mount hides the host path.
if [[ "${GIT_TOP}" == "${HOST_DIR}" && -n "${GIT_COMMON_DIR}" &&
"${GIT_COMMON_DIR}/" != "${HOST_DIR}/"* ]]; then
if outside_container_paths "${HOST_DIR}" &&
outside_container_paths "${GIT_COMMON_DIR}"; then
GIT_MOUNTS=(
-v "${HOST_DIR}:${HOST_DIR}"
-v "${GIT_COMMON_DIR}:${GIT_COMMON_DIR}"
)
CONTAINER_WORKDIR=${HOST_DIR}
else
echo "Warning: ${HOST_DIR} and its git data in ${GIT_COMMON_DIR} cannot" \
"both be mounted at their host paths, because one of them is under" \
"/workspace or ${CONTAINER_HOME}. Git does not work in the container." >&2
( "${GIT_COMMON_DIR}/" != "${HOST_DIR}/"* ||
( -n "${mount_prefix}" && "${HOST_DIR}" != /workspace && -f "${HOST_DIR}/.git" ) ) ]]; then
CONTAINER_WORKDIR="${mount_prefix}${HOST_DIR}"
if [[ "${CONTAINER_WORKDIR}" != /workspace ]]; then
GIT_MOUNTS+=(-v "${HOST_DIR}:${CONTAINER_WORKDIR}")
fi
if [[ "${GIT_COMMON_DIR}/" != "${HOST_DIR}/"* ]]; then
GIT_MOUNTS+=(-v "${GIT_COMMON_DIR}:${mount_prefix}${GIT_COMMON_DIR}")
fi
if [[ -n "${mount_prefix}" && -f "${HOST_DIR}/.git" ]]; then
# Overlay the gitfile so its absolute target uses the new prefix.
# Git still writes to the shared metadata through the directory mount.
git_dir=$(git -C "${HOST_DIR}" rev-parse --absolute-git-dir)
git_dir=$(cd "${git_dir}" && pwd -P)
# Keep the source on a path already shared with the container engine.
GIT_LINK_DIR=$(mktemp -d "${git_dir}/claude-link.XXXXXX")
trap 'rm -rf -- "${GIT_LINK_DIR}"' EXIT
printf 'gitdir: %s%s\n' "${mount_prefix}" "${git_dir}" > "${GIT_LINK_DIR}/gitfile"
GIT_MOUNTS+=(-v "${GIT_LINK_DIR}/gitfile:${CONTAINER_WORKDIR}/.git:ro")
fi
fi

Expand Down Expand Up @@ -197,13 +212,24 @@ DOCKER_RUN_ARGS+=(-v "${BAZEL_CACHE_DIR}:${CONTAINER_HOME}/.cache/bazel")

# --- Run ---
if [[ "${SHELL_MODE}" -eq 1 ]]; then
exec docker run \
"${DOCKER_RUN_ARGS[@]}" \
"${CLAUDE_IMAGE}" \
bash
command=(bash)
else
exec docker run \
"${DOCKER_RUN_ARGS[@]}" \
"${CLAUDE_IMAGE}" \
claude --dangerously-skip-permissions "${CLAUDE_ARGS[@]}"
command=(claude --dangerously-skip-permissions "${CLAUDE_ARGS[@]}")
fi

if [[ -z "${GIT_LINK_DIR}" ]]; then
exec docker run "${DOCKER_RUN_ARGS[@]}" "${CLAUDE_IMAGE}" "${command[@]}"
fi

# Wait for Docker before removing the temporary bind source. Keep stdin open
# and pass signals sent to the wrapper through to the Docker client.
docker run "${DOCKER_RUN_ARGS[@]}" "${CLAUDE_IMAGE}" "${command[@]}" <&0 &
docker_pid=$!
forward_signal() {
kill -s "$1" "${docker_pid}" 2>/dev/null || return 0
wait "${docker_pid}" || true
}
trap 'forward_signal HUP' HUP
trap 'forward_signal INT' INT
trap 'forward_signal TERM' TERM
wait "${docker_pid}"
173 changes: 173 additions & 0 deletions docker/test-claude-worktree-paths.sh
Original file line number Diff line number Diff line change
@@ -0,0 +1,173 @@
#!/usr/bin/env bash
# Run only on a disposable Linux host with empty, writable /workspace and
# /home/claude-user directories. The test needs Git, Bash and a container engine.
set -euo pipefail

SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd -P)"
for dir in /workspace /home/claude-user; do
if [[ ! -d "${dir}" || ! -w "${dir}" || -n "$(ls -A "${dir}")" ]]; then
echo "Test requires an empty, writable ${dir}" >&2
exit 1
fi
done

tmp=$(mktemp -d)
workspace_fixture=$(mktemp -d /workspace/claude-test.XXXXXX)
home_fixture=$(mktemp -d /home/claude-user/claude-test.XXXXXX)
trap 'rm -rf "${tmp}" "${workspace_fixture}" "${home_fixture}"' EXIT

export GIT_CONFIG_GLOBAL=/dev/null GIT_CONFIG_SYSTEM=/dev/null
export GIT_AUTHOR_NAME=test GIT_AUTHOR_EMAIL=test@example.invalid
export GIT_COMMITTER_NAME=test GIT_COMMITTER_EMAIL=test@example.invalid
# Resolve the real engine before adding the test shim to PATH.
TEST_ENGINE=$(command -v "${CONTAINER_ENGINE:-docker}")
export TEST_ENGINE
export TEST_ENGINE_HOME="${HOME}"
export TEST_ENTRYPOINT="${SCRIPT_DIR}/claude-entrypoint.sh"
export TEST_SETUP="${tmp}/entrypoint"
image="${TEST_IMAGE:-openroad/flow-ubuntu26.04-dev:latest}"

mkdir -p "${tmp}/bin" "${tmp}/settings/.claude" "${tmp}/settings/.cache/bazel-claude"
cat > "${TEST_SETUP}" <<'SH'
#!/usr/bin/env bash
set -e
mkdir -p /etc/sudoers.d
exec /test-entrypoint.sh "$@"
SH
cat > "${tmp}/bin/docker" <<'SH'
#!/usr/bin/env bash
engine_args=()
if [[ "${TEST_ENGINE##*/}" == podman ]]; then
export HOME="${TEST_ENGINE_HOME}"
engine_args+=(--userns keep-id --security-opt label=disable)
fi
case "$1" in
image) exec "${TEST_ENGINE}" "$@" ;;
run)
shift
exec "${TEST_ENGINE}" run "${engine_args[@]}" --user 0:0 --network none \
--cap-drop ALL --cap-add CHOWN --cap-add SETUID --cap-add SETGID \
--cap-add DAC_OVERRIDE --security-opt no-new-privileges \
-v "${TEST_ENTRYPOINT}:/test-entrypoint.sh:ro" \
-v "${TEST_SETUP}:/test-setup.sh:ro" \
--entrypoint /test-setup.sh "$@"
;;
*) exit 1 ;;
esac
SH
chmod +x "${TEST_SETUP}" "${tmp}/bin/docker"

cat > "${tmp}/settings/.gitconfig" <<'CONFIG'
[user]
name = test
email = test@example.invalid
CONFIG
echo saved > "${tmp}/settings/.claude.json"

git init -q "${tmp}/module"
echo module > "${tmp}/module/content"
git -C "${tmp}/module" add content
git -C "${tmp}/module" commit -qm module

make_main() {
git init -q "$1"
cp "${SCRIPT_DIR}/../claude.sh" "$1/claude.sh"
echo initial > "$1/content"
git -C "$1" -c protocol.file.allow=always submodule add -q "${tmp}/module" module
git -C "$1" add claude.sh content
git -C "$1" commit -qm initial
}

make_worktree() {
git -C "$1" worktree add --detach -q "$2"
git -C "$2" -c protocol.file.allow=always submodule update --init -q
}

run_case() {
local checkout=$1 name=$2 original original_module ref git_dir
original=$(cat "${checkout}/.git") || return 1
original_module=$(cat "${checkout}/module/.git") || return 1
git_dir=$(git -C "${checkout}" rev-parse --absolute-git-dir) || return 1
echo fixture > "${tmp}/settings/.claude/settings.json"
rm -f "${tmp}/settings/.cache/bazel-claude/marker"
if ! env -u SSH_AUTH_SOCK -u ANTHROPIC_API_KEY -u AWS_ACCESS_KEY_ID \
-u AWS_SECRET_ACCESS_KEY -u GOOGLE_APPLICATION_CREDENTIALS -u BAZEL_CACHE_DIR \
HOME="${tmp}/settings" PATH="${tmp}/bin:${PATH}" \
bash "${checkout}/claude.sh" --shell --image "${image}" --name "claude-git-test-$$" <<'SH'
set -eu
test "$(git rev-parse --show-toplevel)" = "$(pwd -P)"
test "$(git -C module rev-parse --show-toplevel)" = "$(pwd -P)/module"
status=$(git status --porcelain)
test -z "${status}"
test "$(git -C module show HEAD:content)" = module
git switch -qc "test-$(basename "$(git rev-parse --absolute-git-dir)")"
echo modified > content
git add content
git -c commit.gpgsign=false commit -qm modified
test "$(cat /workspace/content)" = modified
test "$(git config --get gc.worktreePruneExpire)" = never
test "$(cat "${HOME}/.claude/settings.json")" = fixture
test "$(cat "${HOME}/.claude.json")" = saved
if (echo changed >> "${HOME}/.gitconfig") 2>/dev/null; then
exit 1
fi
echo updated > "${HOME}/.claude/settings.json"
touch "${HOME}/.cache/bazel/marker"
SH
then
echo "FAIL: ${name}" >&2
return 1
fi
ref=$(git -C "${checkout}" symbolic-ref HEAD) || return 1
if compgen -G "${git_dir}/claude-link.*" > /dev/null; then
echo "FAIL: ${name}: temporary Git pointer was left behind" >&2
return 1
fi
if [[ "$(cat "${checkout}/.git")" != "${original}" ||
"$(cat "${checkout}/module/.git")" != "${original_module}" ||
"$(git -C "${checkout}" show "${ref}:content")" != modified ||
"$(cat "${tmp}/settings/.claude/settings.json")" != updated ||
! -f "${tmp}/settings/.cache/bazel-claude/marker" ]]; then
echo "FAIL: ${name}: unexpected host state" >&2
return 1
fi
echo "PASS: ${name}"
}

make_main "${tmp}/main"
make_main "${workspace_fixture}/main"
make_main "${home_fixture}/main"
make_worktree "${tmp}/main" "${workspace_fixture}/worktree"
make_worktree "${tmp}/main" "${home_fixture}/worktree"
git -C "${workspace_fixture}/main" -c worktree.useRelativePaths=true \
worktree add --detach -q "${tmp}/workspace-data"
git -C "${tmp}/workspace-data" -c protocol.file.allow=always submodule update --init -q
make_worktree "${home_fixture}/main" "${tmp}/home-data"

# A linked checkout can contain its main repository after the main
# repository moves and Git repairs the links.
nested_checkout="${workspace_fixture}/nested"
make_main "${tmp}/nested-main"
git -C "${tmp}/nested-main" worktree add --detach -q "${nested_checkout}"
mv "${tmp}/nested-main" "${nested_checkout}/main"
git -C "${nested_checkout}/main" worktree repair "${nested_checkout}"
echo /main/ >> "${nested_checkout}/main/.git/info/exclude"
git -C "${nested_checkout}" -c protocol.file.allow=always submodule update --init -q

failed=0
run_case "${workspace_fixture}/worktree" "worktree under /workspace" || failed=1
run_case "${home_fixture}/worktree" "worktree under /home/claude-user" || failed=1
run_case "${tmp}/workspace-data" "Git data under /workspace" || failed=1
run_case "${tmp}/home-data" "Git data under /home/claude-user" || failed=1
run_case "${nested_checkout}" "Git data inside the worktree" || failed=1

# Use /workspace itself only after removing this test's nested fixtures.
rm -rf "${workspace_fixture}"
make_worktree "${tmp}/main" /workspace
run_case /workspace "worktree at /workspace" || failed=1
# The caller provides /workspace. Remove the fixture files and let the exit
# trap remove the temporary repository that stores their Git data.
rm -rf -- /workspace/{.git,.gitmodules,claude.sh,content,module}
workspace_entries=$(ls -A /workspace)
test -z "${workspace_entries}"
exit "${failed}"
15 changes: 11 additions & 4 deletions docs/user/ClaudeCode.md
Original file line number Diff line number Diff line change
Expand Up @@ -93,7 +93,7 @@ are mounted so their contents survive:
| `~/.claude/` | `~/.claude/` | Credentials, settings, conversation history |
| `~/.cache/bazel-claude/` | `~/.cache/bazel/` | Bazel external dependencies |
| `~/.gitconfig` | `~/.gitconfig` | Git identity (read-only) |
| Worktree and main `.git` (worktree only) | Same host paths | Git refs, objects, hooks, config |
| Worktree and main `.git` (worktree only) | Host paths, or paths under `/tmp/claude-worktree` if they overlap a container mount | Git refs, objects, hooks, config |
| `$SSH_AUTH_SOCK` | forwarded | SSH agent for git over SSH |

## Environment variables
Expand Down Expand Up @@ -167,16 +167,20 @@ The shell starts in the worktree's host path.
The worktree's `.git` file and the `.git` files of its submodules point to these paths, so git works in the container.
The entrypoint sources `env.sh` from there, so `OPENROAD`, `FLOW_HOME` and `PATH` use the host path too.
Rebuild the image with `./claude.sh --build` to get this entrypoint.
The worktree is also at `/workspace`, but git links in submodules do not resolve from that path.
If one of these host paths is under `/workspace` or `/home/claude-user`, the wrapper prints a warning and adds no mounts, and git does not work in the container.
The worktree is also at `/workspace`.
Use the start path for Git commands in submodules when `/workspace` is an alias for the worktree.
If a host path would overlap `/workspace` or `/home/claude-user`, the wrapper adds `/tmp/claude-worktree` before both host paths.
It starts Claude Code or the shell at the resulting worktree path and uses a temporary Git pointer there.
Submodules in a relocated worktree use the relative Git links that Git creates during normal initialization.
A worktree at exactly `/workspace` can use the existing checkout mount if its Git data is outside the reserved paths.

The paths of the other worktrees do not exist in the container, so git sees them as stale.
The wrapper sets `gc.worktreePruneExpire=never` in the container, so `git gc` keeps their records.
`git gc` still removes the record of a worktree that has no index file.
Do not run `git worktree prune` or `git worktree repair` in the container: they change the records of the other worktrees.

The start directory is part of some keys and caches.
Claude Code stores the history of a worktree session under the host path, not under `/workspace`, so earlier `/workspace` sessions of that worktree do not resume.
Claude Code stores the history of a worktree session under its start path, so changing that path changes which sessions can resume.
Bazel uses a new output base, and a CMake build directory that you configured under `/workspace` must be configured again.

Check the mounts with a stub `docker` command, without a container engine:
Expand All @@ -185,6 +189,9 @@ Check the mounts with a stub `docker` command, without a container engine:
bash docker/test-claude-sh.sh
```

The Claude Docker CI workflow also runs `docker/test-claude-worktree-paths.sh` on a disposable Linux runner.
It checks Git in the launched shell, including the initialized submodule and writes to the original checkout.

## Security model

Claude Code runs with `--dangerously-skip-permissions` **inside** the
Expand Down