diff --git a/README.md b/README.md
new file mode 100644
index 0000000..e198879
--- /dev/null
+++ b/README.md
@@ -0,0 +1,111 @@
+# Nix GitLab CI
+
+[![built with nix](https://img.shields.io/static/v1?logo=nixos&logoColor=white&label=&message=Built%20with%20Nix&color=41439a)](https://builtwithnix.org)
+[![pipeline status](https://gitlab.com/TECHNOFAB/nix-gitlab-ci/badges/main/pipeline.svg)](https://gitlab.com/TECHNOFAB/nix-gitlab-ci/-/commits/main)
+![License: MIT](https://img.shields.io/gitlab/license/technofab/nix-gitlab-ci)
+[![Latest Release](https://gitlab.com/TECHNOFAB/nix-gitlab-ci/-/badges/release.svg)](https://gitlab.com/TECHNOFAB/nix-gitlab-ci/-/releases)
+[![Support me](https://img.shields.io/badge/Support-me-orange)](https://tec.tf/#support)
+[![Docs](https://img.shields.io/badge/Read-Docs-orange)](https://nix-gitlab-ci.projects.tf)
+
+Flake module which allows generating a `.gitlab-ci.yml` from Nix.
+
+This allows easily using any Nix package in CI.
+
+Also makes it possible to split CI parts in a separate module which can be imported in multiple projects.
+
+## Usage (with flake-parts)
+
+```nix
+# flake.nix
+{
+  ...
+  inputs.nix-gitlab-ci.url = "gitlab:TECHNOFAB/nix-gitlab-ci/<version>?dir=lib";  # recommendation: pin to the latest release/version
+  
+  outputs = {...}: flake-parts.lib.mkFlake {...} {
+    imports = [
+      inputs.nix-gitlab-ci.flakeModule
+    ];
+    ...
+    
+    perSystem = {pkgs, ...}: {
+      ci = {
+        config = {
+          # configure Nix-GitLab-CI here, see docs for options
+        };
+        pipelines."default" = {
+          stages = ["test"];
+          jobs = {
+            "test" = {
+              stage = "test";
+              nix.deps = [pkgs.unixtools.ping];
+              script = [
+                "ping -c 5 8.8.8.8"
+              ];
+            };
+          };
+        };
+        # runs on a merge request for example
+        pipelines."merge_request_event" = {
+          stages = ["some_stage"];
+          jobs = { ... };
+        };
+      };
+      ...
+    }
+  }
+}
+```
+
+Now either use this in your .gitlab-ci.yml or setup Soonix to auto generate this 
+file for you with the right version (see the [docs][docs-soonix] for more).
+
+```yaml
+# .gitlab-ci.yml
+include:
+  - component: gitlab.com/TECHNOFAB/nix-gitlab-ci/nix-gitlab-ci@<version>  # recommendation: pin to the latest release/version (don't use "main" etc.)
+    inputs:
+      version: <version>  # docker image tag, use the same version as a above
+```
+
+## Usage (directly)
+
+```nix
+let
+  cilib = inputs.nix-gitlab-ci.lib {inherit pkgs;};
+in
+  cilib.mkCI {
+    config = ...;
+    pipelines."default" = ...;
+  };
+  # exposes `soonix` for the soonix hook and `packages` which contain the configs, jobs etc.
+```
+
+## Utilities
+
+### Disable Caching temporarily
+
+To disable any of the provided caches for a pipeline one can set `NIX_CI_DISABLE_CACHE` to
+anything non-empty (eg. "yes") when triggering the pipeline.
+
+The `build:nix-ci` job has a different special environment variable `NIX_CI_FORCE_BUILD`
+(useful if the generated pipeline in the cache is outdated, this will build it again).
+
+### Run Jobs locally
+
+You can run any job's script (+ before and after) locally with Nix for easier testing:
+
+```sh
+#                                /  pipeline name, like "default"
+nix run .#gitlab-ci:pipeline:<pipeline name>:job:<name>
+```
+
+There is also `.#gitlab-ci:pipeline:<pipeline name>:job-deps:<name>` which generates and exports the required environment variables for each job:
+
+- PATH (with all deps)
+- any custom env variables which contain store paths to not break stuff when switching archs
+
+## Thanks to
+
+Some parts of this implementation are adapted/inspired from https://gitlab.com/Cynerd/gitlab-ci-nix
+
+[docs-soonix]: https://nix-gitlab-ci.projects,tf/soonix "Soonix Integration"