From 9a4ae00f20dd658b95841e10b7b2976429c7fed7 Mon Sep 17 00:00:00 2001
From: Copilot <223556219+Copilot@users.noreply.github.com>
Date: Wed, 1 Jul 2026 17:41:13 +0200
Subject: [PATCH] docs: add ready-to-use CI/CD templates for major platforms

Adds a new guide page with copy-paste semrel release pipeline snippets
for GitHub Actions, GitLab CI, Bitbucket Pipelines, CircleCI, and Travis CI.

Closes #7.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Signed-off-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 astro.config.mjs                           |   1 +
 src/content/docs/guide/ci-cd-templates.mdx | 159 +++++++++++++++++++++
 2 files changed, 160 insertions(+)
 create mode 100644 src/content/docs/guide/ci-cd-templates.mdx

diff --git a/astro.config.mjs b/astro.config.mjs
index a75ba1a..89bfd94 100644
--- a/astro.config.mjs
+++ b/astro.config.mjs
@@ -252,6 +252,7 @@ export default defineConfig({
             { label: 'Monorepo', link: '/guide/monorepo/' },
             { label: 'Docker', link: '/guide/docker/' },
             { label: 'CI Outputs', link: '/guide/ci-outputs/' },
+            { label: 'CI/CD Templates', link: '/guide/ci-cd-templates/', ...newBadge('2026-07-01') },
             { label: 'Schemas', link: '/guide/schemas/' },
             { label: 'Plugin Development', link: '/guide/plugin-development/' },
           ],
diff --git a/src/content/docs/guide/ci-cd-templates.mdx b/src/content/docs/guide/ci-cd-templates.mdx
new file mode 100644
index 0000000..eafe04c
--- /dev/null
+++ b/src/content/docs/guide/ci-cd-templates.mdx
@@ -0,0 +1,159 @@
+---
+title: CI/CD Templates
+description: Ready-to-use, copy-paste semrel pipeline templates for GitHub Actions, GitLab CI, Bitbucket Pipelines, CircleCI, and Travis CI.
+---
+
+import { Aside, Tabs, TabItem } from '@astrojs/starlight/components';
+
+Copy one of the templates below into your project to get a working semrel release
+pipeline in under a minute. Every snippet triggers on pushes to your default branch
+and runs `semrel release` with sane defaults.
+
+<Aside type="tip">
+  All templates assume `.semrel.yaml` at the repository root. Adjust `working-directory`
+  / `path` settings for monorepos — see the [Monorepo guide](/guide/monorepo/).
+</Aside>
+
+<Tabs>
+<TabItem label="GitHub Actions">
+
+Uses the [official composite action](https://github.com/SemRels/semrel) — no
+Node.js wrapper, just downloads and builds the Go binary for the runner.
+
+```yaml
+# .github/workflows/release.yml
+name: Release
+
+on:
+  push:
+    branches: [main]
+
+concurrency:
+  group: release
+  cancel-in-progress: false
+
+permissions:
+  contents: write
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - uses: SemRels/semrel@v0
+        id: semrel
+        with:
+          dry-run: 'false'
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Use outputs
+        if: steps.semrel.outputs.released == 'true'
+        run: echo "Released ${{ steps.semrel.outputs.version }}"
+```
+
+</TabItem>
+<TabItem label="GitLab CI">
+
+Uses the [GitLab CI release component](https://github.com/SemRels/condition-gitlab-ci/blob/main/templates/release.yml).
+
+```yaml
+# .gitlab-ci.yml
+include:
+  - remote: 'https://raw.githubusercontent.com/SemRels/condition-gitlab-ci/main/templates/release.yml'
+    inputs:
+      dry_run: "false"
+```
+
+Set a masked, protected `SEMREL_TOKEN` CI/CD variable (Settings → CI/CD → Variables)
+with permission to push tags and create releases.
+
+</TabItem>
+<TabItem label="Bitbucket Pipelines">
+
+```yaml
+# bitbucket-pipelines.yml
+image: golang:1.25
+
+pipelines:
+  branches:
+    main:
+      - step:
+          name: Release
+          script:
+            - go install github.com/SemRels/semrel/cmd/semrel@latest
+            - export PATH="$(go env GOPATH)/bin:$PATH"
+            - semrel release
+```
+
+Add `SEMREL_TOKEN` (and any provider-specific secrets) as a **secured** repository
+variable under Repository settings → Pipelines → Repository variables.
+
+</TabItem>
+<TabItem label="CircleCI">
+
+```yaml
+# .circleci/config.yml
+version: 2.1
+
+jobs:
+  release:
+    docker:
+      - image: golang:1.25
+    steps:
+      - checkout
+      - run:
+          name: Install semrel
+          command: go install github.com/SemRels/semrel/cmd/semrel@latest
+      - run:
+          name: Run semrel release
+          command: semrel release
+
+workflows:
+  release:
+    jobs:
+      - release:
+          filters:
+            branches:
+              only: main
+```
+
+</TabItem>
+<TabItem label="Travis CI">
+
+```yaml
+# .travis.yml
+language: go
+go:
+  - "1.25"
+
+branches:
+  only:
+    - main
+
+install:
+  - go install github.com/SemRels/semrel/cmd/semrel@latest
+
+script:
+  - semrel release
+```
+
+</TabItem>
+</Tabs>
+
+## Common environment variables
+
+All templates read the same [configuration file](/guide/configuration/) and honor
+these environment variables regardless of the CI platform:
+
+| Variable | Description |
+| --- | --- |
+| `SEMREL_TOKEN` | Token used by provider/publisher plugins (create tags, releases, comments) |
+| `SEMREL_DRY_RUN` | Set to `true` to simulate a release without side effects |
+| `SEMREL_CONFIG` | Override the path to `.semrel.yaml` |
+
+See [CI Outputs](/guide/ci-outputs/) for how to consume the computed version, tag,
+and changelog in downstream steps across GitHub Actions and GitLab CI.