ci: add reusable GitHub workflows and document caller usage

.github/workflows/enforce-pr-targets.yml

@@ -0,0 +1,24 @@
+name: enforce-pr-targets
+
+on:
+  workflow_call:
+
+jobs:
+  check-pr-targets:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check PR base and head branches
+        run: |
+          set -euo pipefail
+          BASE="${{ github.base_ref }}"
+          HEAD="${{ github.head_ref }}"
+
+          if [[ "$BASE" == "main" ]]; then
+            case "$HEAD" in
+              release/*|hotfix/*) exit 0 ;;
+              *)
+                echo "Pull requests into main must come from release/* or hotfix/* branches (got: ${HEAD})."
+                exit 1
+                ;;
+            esac
+          fi

.github/workflows/pr-title.yml

@@ -0,0 +1,35 @@
+name: pr-title
+
+on:
+  workflow_call:
+    inputs:
+      types:
+        description: Allowed Conventional Commit types (one per line)
+        required: false
+        type: string
+        default: |
+          build
+          chore
+          ci
+          docs
+          feat
+          fix
+          model
+          perf
+          refactor
+          revert
+          style
+          test
+
+jobs:
+  main:
+    name: Validate PR title
+    runs-on: ubuntu-latest
+    permissions:
+      pull-requests: read
+    steps:
+      - uses: amannn/action-semantic-pull-request@v6
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        with:
+          types: ${{ inputs.types }}

.github/workflows/pre-release.yml

@@ -0,0 +1,22 @@
+name: pre-release
+
+on:
+  workflow_call:
+
+jobs:
+  check-changelog:
+    runs-on: ubuntu-latest
+    permissions:
+      pull-requests: read
+    steps:
+      - name: Get changed files
+        id: changed-files
+        uses: step-security/changed-files@v45
+        with:
+          files: |
+            CHANGELOG.md
+      - name: Ensure changelog updated
+        if: steps.changed-files.outputs.any_changed == 'false'
+        run: |
+          echo "CHANGELOG.md file must be updated with release notes"
+          exit 1

.github/workflows/security.yml

@@ -0,0 +1,13 @@
+name: dependency-review
+
+on:
+  workflow_call:
+
+jobs:
+  dependency-review:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/dependency-review-action@v5

README.md

@@ -1,23 +1,67 @@
 # .github
 
-This repository contains organization-wide community health files for [DataKind](https://github.com/datakind). These files automatically apply to all repositories in the DataKind GitHub organization that don't have their own local versions.
+Org-wide defaults for [DataKind](https://github.com/datakind): community health files (auto-inherited) and reusable workflows (opt-in per repo).
 
-## What's in here
+## Community health files
 
 | File | Purpose |
 |---|---|
-| `CONTRIBUTING.md` | Contribution guidelines, branching strategy, PR process, testing requirements, and approval workflow |
-| `.github/PULL_REQUEST_TEMPLATE.md` | Standard pull request template with SOC 2 change management checklist |
-| `CODE_OF_CONDUCT.md` | Organization-wide code of conduct |
-| `SECURITY.md` | Security vulnerability reporting policy |
+| `CONTRIBUTING.md` | Branching, PR process, testing, approvals |
+| `.github/PULL_REQUEST_TEMPLATE.md` | PR template with SOC 2 checklist |
+| `CODE_OF_CONDUCT.md` | Code of conduct |
+| `SECURITY.md` | Vulnerability reporting |
 
+Repos override any of these by adding a local copy.
 
-## How it works
+## Reusable workflows
 
-GitHub automatically uses these files as defaults for any repo in the organization that doesn't have its own copy. For example, when someone opens a pull request on any DataKind repo, they'll see the standard PR template — unless that repo has its own template.
+Live under `.github/workflows/`. Not inherited — add a caller in each repo:
 
-**A repo can override any of these files** by adding its own version locally. The local copy always takes precedence.
+```yaml
+jobs:
+  example:
+    uses: datakind/.github/.github/workflows/<name>.yml@main
+```
+
+| Workflow | Purpose | Caller trigger |
+|---|---|---|
+| `enforce-pr-targets` | PRs to `main` only from `release/*` or `hotfix/*` | `pull_request` → `develop`, `main` |
+| `pr-title` | Conventional Commits PR titles | `pull_request` (opened, edited, synchronize) |
+| `pre-release` | `CHANGELOG.md` required on PRs to `main` | `pull_request` → `main` |
+| `dependency-review` | Dependency Review on PRs | `pull_request` |
+
+### Caller examples
+
+```yaml
+# enforce-pr-targets
+jobs:
+  enforce:
+    uses: datakind/.github/.github/workflows/enforce-pr-targets.yml@main
+
+# pr-title
+jobs:
+  validate:
+    permissions:
+      pull-requests: read
+    uses: datakind/.github/.github/workflows/pr-title.yml@main
+
+# pre-release
+jobs:
+  check:
+    permissions:
+      pull-requests: read
+    uses: datakind/.github/.github/workflows/pre-release.yml@main
+
+# dependency-review
+permissions:
+  contents: read
+jobs:
+  review:
+    uses: datakind/.github/.github/workflows/security.yml@main
+```
+
+`pr-title` accepts optional `types` input (multiline). Defaults include `model`.
 
 ## Who can edit
 
-Changes to this repository affect all DataKind repos that inherit from it. Write access is restricted to authorized personnel. If you'd like to propose a change, open a pull request.
+Changes here affect all org repos that inherit from it. Open a PR to propose changes.