diff --git a/.github/workflows/publish-pypi.yml b/.github/workflows/publish-pypi.yml
deleted file mode 100644
index 27fb158..0000000
--- a/.github/workflows/publish-pypi.yml
+++ /dev/null
@@ -1,94 +0,0 @@
-name: Upload Python Package
-
-on:
-  workflow_call:
-    inputs:
-      python-version:
-        description: 'Python version to build with'
-        required: false
-        default: '3.x'
-        type: string
-      package-name:
-        description: 'PyPI package name, used to construct the PyPI URL (e.g. my-package)'
-        required: true
-        type: string
-      environment-name:
-        description: 'GitHub environment to use for the PyPI publish job'
-        required: false
-        default: 'pypi'
-        type: string
-      working-directory:
-        description: 'Working directory for the build, relative to the repo root. Useful for monorepos.'
-        required: false
-        default: '.'
-        type: string
-      use-uv:
-        description: 'Use uv to build the package instead of pip + build'
-        required: false
-        default: false
-        type: boolean
-
-jobs:
-  build:
-    name: Build distribution
-    runs-on: ubuntu-latest
-    permissions:
-      contents: read
-    # Apply working-directory to all run steps in this job
-    defaults:
-      run:
-        working-directory: ${{ inputs.working-directory }}
-
-    steps:
-      - uses: actions/checkout@v4
-
-      # When using uv, Python is managed by uv itself via the python-version input.
-      # When using pip, setup-python handles it instead.
-      - name: Set up Python
-        if: ${{ !inputs.use-uv }}
-        uses: actions/setup-python@v5
-        with:
-          python-version: ${{ inputs.python-version }}
-
-      - name: Set up uv
-        if: inputs.use-uv
-        uses: astral-sh/setup-uv@v5
-        with:
-          python-version: ${{ inputs.python-version }}
-
-      - name: Install build dependencies
-        if: ${{ !inputs.use-uv }}
-        run: |
-          python -m pip install --upgrade pip
-          pip install build
-
-      - name: Build package
-        run: ${{ inputs.use-uv && 'uv build' || 'python -m build' }}
-
-      - name: Store the distribution packages
-        uses: actions/upload-artifact@v4
-        with:
-          name: python-package-distributions
-          # upload-artifact paths are relative to the workspace root, not working-directory,
-          # so we need to include the working-directory prefix explicitly.
-          path: ${{ inputs.working-directory }}/dist/
-
-  publish-to-pypi:
-    name: Publish Python distribution to PyPI
-    needs: build
-    runs-on: ubuntu-latest
-    environment:
-      name: ${{ inputs.environment-name }}
-      url: https://pypi.org/p/${{ inputs.package-name }}
-    permissions:
-      id-token: write # required for OIDC-based PyPI publishing (no API token needed)
-
-    steps:
-      - name: Download all the dists
-        uses: actions/download-artifact@v4
-        with:
-          name: python-package-distributions
-          path: dist/
-
-      - name: Publish distribution to PyPI
-        uses: pypa/gh-action-pypi-publish@release/v1
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..5e2bceb
--- /dev/null
+++ b/README.md
@@ -0,0 +1,9 @@
+# Workflows
+
+Reusable GitHub Actions workflows for common CI/CD tasks, designed to be easily integrated into your projects.
+
+See the [docs](./docs/) for detailed documentation on each workflow, including parameters, usage instructions, and best practices.
+
+See the [samples](./samples/) for example workflows demonstrating how to use these reusable workflows in real-world scenarios.
+
+Note - this repository uses its own workflows to release, so you can check out the [release workflow](./.github/workflows/release.yaml) for a real example of how to use these workflows together in a complete release pipeline.
diff --git a/docs/samples/release.container.md b/docs/samples/release.container.md
new file mode 100644
index 0000000..f7e083b
--- /dev/null
+++ b/docs/samples/release.container.md
@@ -0,0 +1,80 @@
+# Release Container Workflow Sample
+
+This sample workflow demonstrates a complete release pipeline that combines semantic versioning, container publishing, and automated tagging. It's designed to be copied into your project's `.github/workflows/` directory and customised for your specific needs.
+
+The idea is to provide a drop-in model for releasing software, where developers can focus on code, rather than the mechanics of releases. The developer only has to make the decision of what type of release (patch, minor, major, none) and communicate this through their PR title. The workflow then takes care of the rest - generating release notes, creating GitHub releases, building and publishing container images, and tagging them appropriately.
+
+This exists within the existing constraints of Github, mostly that [automated releases cannot trigger other workflows](https://github.com/orgs/community/discussions/25281), so by composing reusable workflows together we can achieve a full release pipeline that is still easy to understand and maintain. The workflow is also designed to be flexible, so you can easily swap out the container publishing step for other types of release artifacts if needed.
+
+## Overview
+
+The workflow performs the following steps:
+
+1. **Semantic Release**: Analyses commits since the last release to determine if a new version should be created, and if so, generates a new Github release with an automatically generated changelog.
+2. **Container Publishing**: Builds and pushes a container image with an `edge` tag (we avoid latest, so this is a pre-release build)
+3. **Semver Tagging**: If a release was created, promotes the edge image to semantic version tags (e.g., `1.2.3`, `1.2`, `1`)
+
+## Prerequisites
+
+- Your repository must follow [conventional commit](https://conventionalcommits.org/) format
+- We recommend `samples/check.pr-title.yaml` to enforce this on pull requests
+- Your repository settings should only allow squash merges, and use the PR title as the commit message for commit messages to be correctly parsed by semantic-release
+- You need a `samples/release.config.js` in your repository root to configure semantic-release
+- You need a `Dockerfile` in your repository root (or update the `dockerfile` parameter)
+
+## Workflow Jobs
+
+### semantic-release
+
+Uses the [`semantic-release.yml`](../semantic-release.md) reusable workflow to:
+
+- Install and run semantic-release
+- Create GitHub releases with automatically generated changelogs
+- Output `release-created` (boolean) and `release-tag` (version string)
+
+### publish-container
+
+Uses the [`publish-container.yml`](../publish-container.md) reusable workflow to:
+
+- Build a multi-architecture container image
+- Tag it with SHA, timestamp, and "edge"
+- Push to the specified container registry
+
+**Parameters:**
+
+- `image-name`: Name of your container image
+- `image-description`: Description for the image
+- `registry`: Container registry (e.g., `ghcr.io`, `docker.io`)
+- `context`: Build context path (usually `.`)
+- `dockerfile`: Path to Dockerfile
+- `platforms`: Target architectures (comma-separated)
+
+### semver-container
+
+Uses the [`semver-container.yml`](../semver-container.md) reusable workflow to:
+
+- Promote the edge image to semantic version tags
+- Only runs if `semantic-release` created a new release
+
+**Parameters:**
+
+- `image-name`: Must match the `publish-container` job
+- `registry`: Must match the `publish-container` job
+- `tag`: Release tag from semantic-release (do not modify)
+
+### Version Pinning
+
+For production use, pin to specific versions:
+
+```yaml
+uses: health-informatics-uon/workflows/.github/workflows/semantic-release.yml@v1.3.0
+```
+
+Check the [releases](https://github.com/health-informatics-uon/workflows/releases) for available versions.
+
+## Usage
+
+1. Copy `samples/release.container.yaml` to your repository's `.github/workflows/release.yaml`
+2. Copy `samples/release.config.js` to your repository root and customise it for your repository
+3. Update the workflow parameters in `release.yaml` (image name, etc.)
+4. Ensure your repository follows the prerequisites (conventional commits, squash merges, etc.)
diff --git a/docs/dependency-review.md b/docs/workflows/dependency-review.md
similarity index 100%
rename from docs/dependency-review.md
rename to docs/workflows/dependency-review.md
diff --git a/docs/pr-title.md b/docs/workflows/pr-title.md
similarity index 100%
rename from docs/pr-title.md
rename to docs/workflows/pr-title.md
diff --git a/docs/publish-container.md b/docs/workflows/publish-container.md
similarity index 100%
rename from docs/publish-container.md
rename to docs/workflows/publish-container.md
diff --git a/docs/publish-pypi.md b/docs/workflows/publish-pypi.md
similarity index 100%
rename from docs/publish-pypi.md
rename to docs/workflows/publish-pypi.md
diff --git a/docs/semantic-release.md b/docs/workflows/semantic-release.md
similarity index 100%
rename from docs/semantic-release.md
rename to docs/workflows/semantic-release.md
diff --git a/docs/semver-container.md b/docs/workflows/semver-container.md
similarity index 100%
rename from docs/semver-container.md
rename to docs/workflows/semver-container.md
diff --git a/samples/check.dependency-review.yaml b/samples/check.dependency-review.yaml
new file mode 100644
index 0000000..ac16f4d
--- /dev/null
+++ b/samples/check.dependency-review.yaml
@@ -0,0 +1,10 @@
+name: 'Dependency Review'
+on: [pull_request]
+
+permissions:
+  contents: read
+
+jobs:
+  dependency-review:
+    uses: health-informatics-uon/workflows/.github/workflows/dependency-review.yml@1.3.0
+    secrets: inherit
diff --git a/samples/check.pr-title.yaml b/samples/check.pr-title.yaml
new file mode 100644
index 0000000..5ad340c
--- /dev/null
+++ b/samples/check.pr-title.yaml
@@ -0,0 +1,15 @@
+name: 'Check PR title'
+
+on:
+  pull_request:
+    types:
+      - opened
+      - reopened
+      - edited
+      - synchronize
+
+jobs:
+  main:
+    uses: health-informatics-uon/workflows/.github/workflows/pr-title.yml@1.3.0
+    permissions:
+      pull-requests: read
diff --git a/samples/publish.pypi.yml b/samples/publish.pypi.yml
new file mode 100644
index 0000000..185397b
--- /dev/null
+++ b/samples/publish.pypi.yml
@@ -0,0 +1,54 @@
+# This workflow will upload a Python Package using Twine when a release is created
+# For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-python#publishing-to-package-registries
+
+name: Upload Python Package
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python
+        uses: actions/setup-python@v3
+        with:
+          python-version: "3.x"
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install build
+      - name: Build package
+        run: python -m build
+      - name: Store the distribution packages
+        uses: actions/upload-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+  
+  publish-to-pypi:
+    name: Publish Python distribution to PyPI
+    needs:
+      - build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/omop-lite
+    permissions:
+      id-token: write
+
+    steps:
+      - name: Download all the dists
+        uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+      - name: Publish distribution 📦 to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
\ No newline at end of file
diff --git a/samples/release.config.js b/samples/release.config.js
new file mode 100644
index 0000000..ced2fab
--- /dev/null
+++ b/samples/release.config.js
@@ -0,0 +1,13 @@
+module.exports = {
+    "branches": ["main"],
+    "tagFormat": "${version}",
+    "preset": "angular",
+    "repositoryUrl": "https://github.com/Health-Informatics-UoN/<YOUR_REPO_NAME>.git",
+    plugins: [
+      '@semantic-release/commit-analyzer',
+      '@semantic-release/release-notes-generator',
+      '@semantic-release/exec',
+      '@semantic-release/github',
+    ],
+    "initialVersion": "1.0.0"
+};
\ No newline at end of file
diff --git a/samples/release.container.yaml b/samples/release.container.yaml
new file mode 100644
index 0000000..1d6347f
--- /dev/null
+++ b/samples/release.container.yaml
@@ -0,0 +1,51 @@
+# Sample workflow for releasing a project using reusable workflows from health-informatics-uon/workflows
+# This demonstrates how to combine semantic-release, container publishing, and semver tagging
+# Customize the placeholders and values below for your specific project
+
+name: Release
+permissions:
+  contents: write
+  pull-requests: write
+  issues: write
+  packages: write
+  id-token: write
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  release:
+    uses: health-informatics-uon/workflows/.github/workflows/semantic-release.yml@1.3.0
+    with:
+      node-version: '24'
+    secrets: inherit
+
+  publish-container:
+    uses: health-informatics-uon/workflows/.github/workflows/publish-container.yml@1.3.0
+    with:
+      # Set your container image name
+      image-name: <YOUR_IMAGE_NAME>
+      # Describe your container image
+      image-description: '<YOUR_IMAGE_DESCRIPTION>'
+      registry: ghcr.io
+      # Path to the build context (usually '.')
+      context: .
+      # Path to your Dockerfile
+      dockerfile: Dockerfile
+      # Target platforms for multi-architecture builds
+      platforms: linux/amd64,linux/arm64
+    secrets: inherit
+
+  semver-container:
+    uses: health-informatics-uon/workflows/.github/workflows/semver-container.yml@1.3.0
+    needs: [release, publish-container]
+    if: needs.release.outputs.release-created == 'true'
+    with:
+      # Your container image name (must match publish-container)
+      image-name: <YOUR_IMAGE_NAME>
+      registry: ghcr.io
+      # Release tag from semantic-release (do not change)
+      tag: ${{ needs.release.outputs.release-tag }}
+    secrets: inherit