From ddbfe348a4daaeb561f9d10b99b314472fb1b8f2 Mon Sep 17 00:00:00 2001
From: drlkf <drlkf@drlkf.net>
Date: Thu, 7 Aug 2025 22:41:09 +0200
Subject: [PATCH] docs: add semantic-release section

---
 profile/README.md           |  8 +++-
 profile/semantic-release.md | 73 +++++++++++++++++++++++++++++++++++++
 2 files changed, 80 insertions(+), 1 deletion(-)
 create mode 100644 profile/semantic-release.md

diff --git a/profile/README.md b/profile/README.md
index 11e5335..6201263 100644
--- a/profile/README.md
+++ b/profile/README.md
@@ -47,11 +47,17 @@ The __haskell_github_trust__ account does not have upload permission, rather it
 on [hackage.haskell.org/upload](https://hackage.haskell.org/upload).
 
 > #### Group Accounts
-> 
+>
 > Occasionally organizations want to have a group / organizational account for a package that is maintained by a group of people. The recommended approach for these cases is to only do package uploads from individual accounts and use the group account only for managing the maintainer list for the package.
 
 In this way you can [upload](https://hackage.haskell.org/upload) any package in this org.
 
+## Organization secrets
+
+Some organization secrets are setup to allow performing actions on the
+organization and publishing to Hackage. Check out the
+[`semantic-release`](semantic-release.md) file to learn more.
+
 ## How to add other people’s packages to the Trust
 
 1. Follow the instructions in [Taking over a package](https://wiki.haskell.org/Taking_over_a_package) with your own Hackage account. Declare your intent to add the package to the Haskell GitHub Trust.
diff --git a/profile/semantic-release.md b/profile/semantic-release.md
new file mode 100644
index 0000000..a075138
--- /dev/null
+++ b/profile/semantic-release.md
@@ -0,0 +1,73 @@
+# Setting up `semantic-release` for Haskell Github Trust packages
+
+Once a version of your package has been uploaded to Hackage and the trust
+account has been added to the maintainers, you can use the [semantic-release
+action](https://github.com/cycjimmy/semantic-release-action) to publish new
+versions automatically. The organization already has everything configured, you
+only need to configure a few things.
+
+In this example, we use the `stack-upload` plugin to upload to hackage, but feel
+free to use the `cabal` actions if you don't like `stack`. We also use `main` as
+the default branch, make sure to modify the snippets if you use a different
+default branch name.
+
+## Install the Github App on your repository
+The first step is to add the [Github
+app](https://github.com/organizations/haskell-github-trust/settings/installations/79745966)
+to your repository by adding it to the selected repositories in `Repository access`.
+
+## Configure `semantic-release` in your repository
+In your repository at the root, configure `semantic-release` by adding the
+`.releaserc.mjs` at the root:
+
+```javascript
+/**
+ * @type {import('semantic-release').GlobalConfig}
+ */
+export default {
+    branches: ["main"],
+    tagFormat: "${version}",
+    plugins: [
+        "semantic-release-stack-upload",
+    ]
+}
+```
+
+## Add the `semantic-release` action to your repository
+In your repository, in `.github/workflows/semantic-release.yaml`, include this snippet:
+
+```yaml
+---
+name: Semantic release
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  build:
+    name: Semantic release
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+
+      - uses: actions/create-github-app-token@v2
+        id: app-token
+        with:
+          app-id: "${{ secrets.SEMANTIC_RELEASE_APP_ID }}"
+          private-key: "${{ secrets.SEMANTIC_RELEASE_PRIVATE_KEY }}"
+
+      - name: Semantic release
+        id: semantic
+        uses: cycjimmy/semantic-release-action@v4
+        env:
+          GITHUB_TOKEN: "${{ steps.app-token.outputs.token }}"
+          HACKAGE_KEY: "${{ secrets.HACKAGE_TOKEN }}"
+
+        with:
+          ci: ${{ github.ref == github.event.repository.default_branch }}
+          extra_plugins: |
+            semantic-release-stack-upload
+```