diff --git a/README.md b/README.md
new file mode 100644
index 0000000000000000000000000000000000000000..c88efdfad9fd9aa74b1e0006c217ae4d9f9f7708
--- /dev/null
+++ b/README.md
@@ -0,0 +1,49 @@
+build-ah-engine
+===
+
+An opinionated utility container for building container images using podman together with gitlab-ci template(s) for reproducible CI/CD pipelines.
+
+The utility allows for multi-architecture builds of container images and their oci manifests. Either on real hardware or emulated using QEMU.
+
+*Note: while easier to use QEMU-based build might be substantially slower for certain types of builds.*
+
+Basic usage
+---
+
+The CI-pipeline of this project illustrates how the template and it's container are used. A minimal x86 
+
+```yaml
+include:
+  # On same gitlab instance
+  - local: /gitlab-ci-template.yml
+  # On remote gitlab instance
+  - remote: https://git.shivering-isles.com/container-library/build-ah-engine/-/raw/2.1.0/gitlab-ci-template.yml
+
+variables:
+  CI_REGISTRY_IMAGE_VERSION: "1.0.0"
+```
+
+Multi-arch example
+---
+
+The variable `CI_CONTAINER_BUILD_ARCHS` controls which architectures to include. It's a `:`-separated list of supported architectures. If the job is picked up by a runner of differing architectures, QEMU is used to cross-compile the container image. On matching architectures the build is done natively. Which runner executes a certain job can be controlled via the jobs `tags`.
+
+```yaml
+include:
+  # On same gitlab instance
+  - local: /gitlab-ci-template.yml
+  # On remote gitlab instance
+  - remote: https://git.shivering-isles.com/container-library/build-ah-engine/-/raw/2.1.0/gitlab-ci-template.yml
+
+variables:
+  CI_REGISTRY_IMAGE_VERSION: "1.0.0"
+  CI_CONTAINER_BUILD_ARCHS: "amd64:arm64"
+
+container-build-x86_64:
+  tags:
+    - x86_64
+
+container-build-arm64:
+  tags:
+    - arm64
+```