From bed1ef45da9f56900f2fce4c57daf17defe3ab9a Mon Sep 17 00:00:00 2001 From: "Amber (ACP Agent)" Date: Thu, 12 Feb 2026 20:28:59 +0000 Subject: [PATCH] docs: add Podman rootless mode instructions and CI test Add comprehensive documentation for running AgentReady container on rootless Podman environments (Fedora, RHEL, CentOS) with: - New "Podman Rootless Mode" section in CONTAINER.md with complete working command - Explanation table for required flags (--userns, --user, GIT_CONFIG_*) - SELinux volume label guidance (:z vs :Z) - Enhanced troubleshooting for Git "dubious ownership" error - Cross-references between sections - CI workflow to verify the documented Podman command works - Test reports archived as artifacts for 30 days Fixes #267 Co-Authored-By: Claude Opus 4.5 --- .github/workflows/container-test.yml | 53 ++++++++++++++++++++++ CONTAINER.md | 67 ++++++++++++++++++++++++++-- 2 files changed, 117 insertions(+), 3 deletions(-) create mode 100644 .github/workflows/container-test.yml diff --git a/.github/workflows/container-test.yml b/.github/workflows/container-test.yml new file mode 100644 index 00000000..35a7ff27 --- /dev/null +++ b/.github/workflows/container-test.yml @@ -0,0 +1,53 @@ +name: Container Tests (Podman Rootless) + +on: + pull_request: + paths: + - 'CONTAINER.md' + - 'Containerfile.scratch' + - '.github/workflows/container-test.yml' + workflow_dispatch: + +jobs: + podman-rootless-test: + name: Podman Rootless Mode Test + runs-on: ubuntu-latest + + steps: + - name: Checkout code + uses: actions/checkout@v6 + + - name: Create test directories + run: mkdir -p ${{ github.workspace }}/test-reports + + - name: Pull AgentReady container + run: podman pull ghcr.io/ambient-code/agentready:latest + + - name: Run assessment with Podman rootless command + run: | + podman run --rm \ + --user $(id -u):$(id -g) \ + --userns=keep-id \ + -e GIT_CONFIG_COUNT=1 \ + -e GIT_CONFIG_KEY_0=safe.directory \ + -e GIT_CONFIG_VALUE_0=/repo \ + -v ${{ github.workspace }}:/repo:ro,z \ + -v ${{ github.workspace }}/test-reports:/reports:z \ + ghcr.io/ambient-code/agentready:latest \ + assess /repo --output-dir /reports + + - name: Verify reports generated + run: | + echo "=== Generated Reports ===" + ls -la ${{ github.workspace }}/test-reports/ + ls ${{ github.workspace }}/test-reports/*.json + ls ${{ github.workspace }}/test-reports/*.html + ls ${{ github.workspace }}/test-reports/*.md + + - name: Upload test reports + uses: actions/upload-artifact@v4 + if: always() + with: + name: podman-rootless-test-reports + path: ${{ github.workspace }}/test-reports/ + retention-days: 30 diff --git a/CONTAINER.md b/CONTAINER.md index 8c758797..f3007df4 100644 --- a/CONTAINER.md +++ b/CONTAINER.md @@ -119,6 +119,48 @@ docker run --rm \ assess /repo --output-dir /reports ``` +## Podman Rootless Mode + +On **rootless Podman** (common on Fedora, RHEL, CentOS), additional flags are required to handle SELinux labeling, UID mapping, and Git security checks. + +### Complete Command + +```bash +podman run --rm -it \ + --user $(id -u):$(id -g) \ + --userns=keep-id \ + -e GIT_CONFIG_COUNT=1 \ + -e GIT_CONFIG_KEY_0=safe.directory \ + -e GIT_CONFIG_VALUE_0=/repo \ + -v /path/to/repo:/repo:ro,z \ + -v /path/to/reports:/reports:z \ + ghcr.io/ambient-code/agentready:latest \ + assess /repo --output-dir /reports +``` + +### Why These Flags? + +| Flag | Purpose | +|------|---------| +| `--userns=keep-id` | Maps container UID to match your host UID, fixing permission mismatches | +| `--user $(id -u):$(id -g)` | Runs the container process as your host user | +| `GIT_CONFIG_*` | Tells Git to trust the mounted `/repo` directory (required for Git 2.35.2+) | +| `:z` (lowercase) | SELinux shared label - allows container access to mounted volumes | + +### When Do I Need This? + +Use the rootless Podman command if you encounter any of these errors: + +- `Path '/repo' is not readable` (SELinux blocking access) +- `SHA is empty, possible dubious ownership` (Git security check) +- `PermissionError: [Errno 13] Permission denied` (UID mismatch) + +### Note on SELinux Labels + +- Use `:z` (lowercase) for shared volumes that multiple containers may access +- Use `:Z` (uppercase) for private volumes exclusive to one container +- Both options relabel the volume for SELinux access + ## CI/CD Integration ### GitHub Actions @@ -195,16 +237,35 @@ Without the `-v ~/agentready-reports:/reports` mount, reports written to `/tmp` ### Permission denied on mounted volumes -Add SELinux context (`:Z` flag) on SELinux systems: +**On rootless Podman** (Fedora, RHEL, CentOS), see the [Podman Rootless Mode](#podman-rootless-mode) section for the complete solution. + +**Quick fix for SELinux only** - add the `:z` label to volumes: ```bash podman run --rm \ - -v $(pwd):/repo:ro,Z \ - -v $(pwd)/agentready-reports:/reports,Z \ + -v $(pwd):/repo:ro,z \ + -v $(pwd)/agentready-reports:/reports:z \ ghcr.io/ambient-code/agentready:latest \ assess /repo --output-dir /reports ``` +### Git "dubious ownership" error + +If you see `SHA is empty, possible dubious ownership`, the container's Git doesn't trust the mounted repository. Add Git safe.directory configuration: + +```bash +podman run --rm \ + -e GIT_CONFIG_COUNT=1 \ + -e GIT_CONFIG_KEY_0=safe.directory \ + -e GIT_CONFIG_VALUE_0=/repo \ + -v $(pwd):/repo:ro \ + -v $(pwd)/agentready-reports:/reports \ + ghcr.io/ambient-code/agentready:latest \ + assess /repo --output-dir /reports +``` + +For the complete solution addressing all rootless Podman issues, see [Podman Rootless Mode](#podman-rootless-mode). + ## Links - **Container Registry**: https://github.com/ambient-code/agentready/pkgs/container/agentready