diff --git a/.woodpecker.yml b/.woodpecker.yml
index 3a3e855..50e2deb 100644
--- a/.woodpecker.yml
+++ b/.woodpecker.yml
@@ -4,3 +4,23 @@ pipeline:
     commands:
       - npm ci
       - npm run build
+  prepare_release:
+    when:
+      event: tag
+      branch: master
+      tag: v*
+    image: node:18-slim
+    commands:
+      - tools/ci-make-release-targz.sh
+  create_release:
+    when:
+      event: tag
+      branch: master
+      tag: v*
+    image: plugins/gitea-release
+    settings:
+      api_key:
+        from_secret: releaser_auth_token
+      base_url: https://git.qcode.ch
+      files: nostrweb.tar.gz
+      note: "automated release by ${CI_SYSTEM_HOST} \nbuild id: ${CI_BUILD_NUMBER}"
diff --git a/README.md b/README.md
index be9c9be..f4b93eb 100644
--- a/README.md
+++ b/README.md
@@ -27,3 +27,18 @@ execute
 
 the build is done using [esbuild](https://esbuild.github.io/), with a config in
 [esbuildconf.js](esbuildconf.js). the result is placed in `dist` directory.
+
+## release
+
+1. make sure `version` field in [package.json](package.json) as seen by remote
+git on **master** branch matches the tag created in the next step.
+2. tag a commit on **master** branch with a `git tag v<vesion>`.
+3. push the tag to the remote: `git push --tags`.
+
+the CI then receives a git tag event, executes `npm run build`, creates
+a tar.gz with all the files found in `dist` directory and uploads it as a new
+release artifact. the release is named after the tag name.
+
+the idea is that nostr web instances are then notified about a new release,
+download the tar.gz archive and update their local copies.
+this is not yet implemented.
diff --git a/tools/ci-make-release-targz.sh b/tools/ci-make-release-targz.sh
new file mode 100755
index 0000000..b0593bd
--- /dev/null
+++ b/tools/ci-make-release-targz.sh
@@ -0,0 +1,16 @@
+#!/bin/sh
+set -e
+
+# assuming the script is run from the repo root dir
+cd dist
+
+# create build metadata
+truncate -s0 build.txt
+echo "remote: $CI_REPO_REMOTE" >> build.txt
+echo "commit: $CI_COMMIT_SHA" >> build.txt
+echo "tag: $CI_COMMIT_TAG" >> build.txt
+echo "build id: $CI_BUILD_NUMBER" >> build.txt
+cat build.txt
+
+# make the release archive in the repo root dir
+tar -czvf ../nostrweb.tar.gz *