diff --git a/.github/workflows/github-actions-claude-shell-test.yml b/.github/workflows/github-actions-claude-shell-test.yml new file mode 100644 index 0000000000..c2f5612aaf --- /dev/null +++ b/.github/workflows/github-actions-claude-shell-test.yml @@ -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 diff --git a/claude.sh b/claude.sh index a66ed2abef..012b9faad6 100755 --- a/claude.sh +++ b/claude.sh @@ -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="" @@ -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 @@ -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}" diff --git a/docker/test-claude-worktree-paths.sh b/docker/test-claude-worktree-paths.sh new file mode 100644 index 0000000000..30610d0010 --- /dev/null +++ b/docker/test-claude-worktree-paths.sh @@ -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}" diff --git a/docs/user/ClaudeCode.md b/docs/user/ClaudeCode.md index 4abfc62bba..aa846acb18 100644 --- a/docs/user/ClaudeCode.md +++ b/docs/user/ClaudeCode.md @@ -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 @@ -167,8 +167,12 @@ 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. @@ -176,7 +180,7 @@ The wrapper sets `gc.worktreePruneExpire=never` in the container, so `git gc` ke 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: @@ -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