diff --git a/Dockerfile b/Dockerfile
index eaca670..92f48c3 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -23,6 +23,9 @@ RUN npm config set fund false && npm config set audit false \
     @semantic-release/exec \
     conventional-changelog-conventionalcommits
 
+COPY entrypoint.sh /usr/local/bin/entrypoint.sh
+RUN chmod +x /usr/local/bin/entrypoint.sh
+
 RUN addgroup -S ci \
  && adduser -S -G ci -h /home/ci -s /bin/bash ci \
  && mkdir -p /workspace /home/ci/.m2 \
@@ -33,6 +36,5 @@ ENV MAVEN_CONFIG=/home/ci/.m2
 WORKDIR /workspace
 
 USER ci
-
-ENTRYPOINT ["/sbin/tini","--"]
+ENTRYPOINT ["/sbin/tini","--","/usr/local/bin/entrypoint.sh"]
 CMD ["/bin/bash","-lc","bash"]
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..336fddb
--- /dev/null
+++ b/README.md
@@ -0,0 +1,50 @@
+# ci-image: MAVEN settings handling
+
+This image supports injecting a Maven `settings.xml` at container start via environment variables.
+
+Environment variables
+- `MAVEN_SETTINGS_BASE64` (preferred): base64-encoded contents of the `settings.xml`. If present, the entrypoint will decode it and write it to `~/.m2/settings.xml`.
+- `MAVEN_SETTINGS`: raw contents of the `settings.xml`. Used only if `MAVEN_SETTINGS_BASE64` is not set.
+
+Notes
+- The entrypoint will create `~/.m2` if it does not exist and set the `settings.xml` file to mode `644`.
+- Use `MAVEN_SETTINGS_BASE64` when your CI system has trouble preserving newlines or special characters in environment variables.
+
+Examples
+
+Build the image:
+
+```bash
+docker build -t my-ci-image .
+```
+
+Provide raw settings (works if your CI preserves newlines):
+
+```bash
+docker run --rm -e MAVEN_SETTINGS="$(cat ~/.m2/settings.xml)" my-ci-image bash -lc 'cat ~/.m2/settings.xml'
+```
+
+Provide base64-encoded settings (recommended to avoid newline issues):
+
+```bash
+docker run --rm -e MAVEN_SETTINGS_BASE64="$(base64 -w0 ~/.m2/settings.xml)" my-ci-image bash -lc 'cat ~/.m2/settings.xml'
+```
+
+GitHub Actions (example)
+
+If you store the plain `settings.xml` as a secret, encode it before setting a secret value (locally):
+
+```bash
+# encode locally then paste into GitHub secret value
+base64 -w0 ~/.m2/settings.xml
+```
+
+Then in your workflow use the secret as-is:
+
+```yaml
+env:
+  MAVEN_SETTINGS_BASE64: ${{ secrets.MAVEN_SETTINGS_BASE64 }}
+uses: docker://my-ci-image
+```
+
+If your CI runner can pass multiline env vars safely, you can instead set `MAVEN_SETTINGS` to the raw XML.
diff --git a/entrypoint.sh b/entrypoint.sh
new file mode 100644
index 0000000..02adfe5
--- /dev/null
+++ b/entrypoint.sh
@@ -0,0 +1,26 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Entrypoint: write `MAVEN_SETTINGS` or decode `MAVEN_SETTINGS_BASE64`
+# into ~/.m2/settings.xml (MAVEN_SETTINGS_BASE64 takes precedence),
+# then exec the container command.
+
+M2_DIR="${HOME:-/root}/.m2"
+
+if [[ -n "${MAVEN_SETTINGS_BASE64:-}" ]]; then
+  mkdir -p "$M2_DIR"
+  # Decode base64 content and write it. If decoding fails the script will error.
+  printf '%s' "$MAVEN_SETTINGS_BASE64" | base64 -d > "$M2_DIR/settings.xml"
+  chmod 644 "$M2_DIR/settings.xml" || true
+elif [[ -n "${MAVEN_SETTINGS:-}" ]]; then
+  mkdir -p "$M2_DIR"
+  # Write the variable contents exactly as provided
+  printf '%s' "$MAVEN_SETTINGS" > "$M2_DIR/settings.xml"
+  chmod 644 "$M2_DIR/settings.xml" || true
+fi
+
+if [[ "$#" -eq 0 ]]; then
+  exec "$SHELL" || exec /bin/sh
+fi
+
+exec "$@"