feat: setup readme (#2)

Reviewed-on: #2
Co-authored-by: Jan Klattenhoff <jan@kjan.email>
Co-committed-by: Jan Klattenhoff <jan@kjan.email>

README.md

@@ -1,2 +1,94 @@
-# ci-template
+# CI Template
 
+A template repository for setting up continuous integration and automatic semantic versioning with Gitea.
+
+## Features
+
+- Automated semantic versioning with [semantic-release](https://github.com/semantic-release/semantic-release)
+- Integration with Gitea for releases
+- Changelog generation
+- Pull request workflows
+
+## Setup Instructions
+
+Follow these steps to set up the CI pipeline and release process:
+
+### 1. Configure Branch Protection
+
+Add yourself to the whitelist in the release branch protection rule.
+
+![Branch protection settings](images/1.png)
+
+Don't forget to save your changes.
+
+![Save changes](images/2.png)
+
+### 2. Create the Release Branch
+
+Create a new branch named `release`.
+
+![Create release branch](images/3.png)
+
+The pipeline for release will start automatically but will fail on the first run. This is expected behavior.
+
+![Initial pipeline failure](images/4.png)
+
+### 3. Create the Initial Version Tag
+
+Run the following commands to create and push the first version tag:
+
+```bash
+git tag v0.1.0
+git push origin tag v0.1.0
+```
+
+### 4. Configure Pull Request Settings
+
+Set up your repository's pull request settings as shown:
+
+![Pull request settings](images/5.png)
+
+### 5. Set Up Deploy Keys
+
+1. Generate an SSH key pair (public and private)
+2. Add the public key to deploy keys named "release" with write access enabled
+
+![Deploy key setup](images/6.png)
+
+3. Add the private key to the runner secret as `DEPLOY_KEY`
+
+![Runner secret](images/7.png)
+
+## Release Process
+
+This template uses semantic versioning through conventional commits. When changes are merged to the release branch, a new version is automatically:
+
+1. Determined based on commit messages
+2. Tagged in Git
+3. Published as a release
+4. Added to the changelog
+
+### Commit Message Format
+
+Follow the [Conventional Commits](https://www.conventionalcommits.org/) specification:
+
+- `feat: add new feature` (triggers MINOR version bump)
+- `fix: resolve bug` (triggers PATCH version bump)
+- `BREAKING CHANGE: redesign API` (triggers MAJOR version bump)
+
+## Getting Started
+
+After completing the setup:
+1. Remove the images directory and this README
+2. Create feature branches from `main` for your work
+3. Make changes and commit using conventional commit format
+4. Create pull requests to `main` (changes should be squashed when merged, although this is not required)
+5. When ready for a release, create a PR from `main` to `release`
+6. The PR to `release` will automatically:
+   - Create a new version based on your commits
+   - Generate a changelog
+   - Merge changes back into `main`
+
+## License
+
+See the [LICENSE](LICENSE) file for details.