From 497d9b151eaa788bcd25048f901cbd5c17a383fc Mon Sep 17 00:00:00 2001 From: Frederik Beimgraben Date: Thu, 30 Oct 2025 19:35:19 +0100 Subject: [PATCH] Update build config --- .github/dependabot.yml | 49 ++++++ .github/workflows/README.md | 170 +++++++++++++++++++++ .github/workflows/makefile.yml | 39 ++++- .github/workflows/release.yml | 93 +++++++++++ Content/Chapters/03_seitenformatierung.tex | 6 +- README.md | 51 +++++++ 6 files changed, 399 insertions(+), 9 deletions(-) create mode 100644 .github/dependabot.yml create mode 100644 .github/workflows/README.md create mode 100644 .github/workflows/release.yml diff --git a/.github/dependabot.yml b/.github/dependabot.yml new file mode 100644 index 0000000..411645c --- /dev/null +++ b/.github/dependabot.yml @@ -0,0 +1,49 @@ +# ============================================================================== +# Dependabot Configuration +# ============================================================================== +# Description: Automated dependency updates for GitHub Actions +# Documentation: https://docs.github.com/en/code-security/dependabot +# ============================================================================== + +version: 2 + +updates: + # ------------------------------------------------------------------------------ + # GitHub Actions Updates + # ------------------------------------------------------------------------------ + # Keep GitHub Actions up to date automatically + - package-ecosystem: "github-actions" + directory: "/" + schedule: + interval: "weekly" + day: "monday" + time: "06:00" + commit-message: + prefix: "ci" + include: "scope" + labels: + - "dependencies" + - "github-actions" + assignees: + - "frederikbeimgraben" + open-pull-requests-limit: 5 + + # ------------------------------------------------------------------------------ + # Docker Updates + # ------------------------------------------------------------------------------ + # Keep Docker base images up to date + - package-ecosystem: "docker" + directory: "/" + schedule: + interval: "monthly" + day: "monday" + time: "06:00" + commit-message: + prefix: "docker" + include: "scope" + labels: + - "dependencies" + - "docker" + assignees: + - "frederikbeimgraben" + open-pull-requests-limit: 3 diff --git a/.github/workflows/README.md b/.github/workflows/README.md new file mode 100644 index 0000000..678d29b --- /dev/null +++ b/.github/workflows/README.md @@ -0,0 +1,170 @@ +# GitHub Actions Workflows + +This directory contains the CI/CD pipeline configurations for the SAT-WiSe-25-26 LaTeX document project. + +## Workflows + +### 1. Build Workflow (`makefile.yml`) + +**Purpose:** Continuous Integration - Build and test the LaTeX document on every push and pull request. + +**Triggers:** +- Push to `main` branch +- Pull requests to `main` branch +- Manual workflow dispatch + +**Features:** +- Builds the document using Docker Compose +- Verifies PDF generation +- Uploads the PDF as an artifact (30-day retention) +- Uploads build logs on failure for debugging + +**Artifacts:** +- `SAT-WiSe-25-26-PDF` - The compiled PDF document +- `build-logs` - LaTeX compilation logs (only on failure) + +### 2. Release Workflow (`release.yml`) + +**Purpose:** Automated release creation when version tags are pushed. + +**Triggers:** +- Push of tags matching `v*.*.*` (e.g., `v1.0.0`) +- Push of tags matching `release-*` (e.g., `release-2024-10`) + +**Features:** +- Builds the document with Docker +- Creates a GitHub release +- Attaches versioned PDF to the release +- Generates release notes automatically +- Archives artifacts for 90 days + +**Artifacts:** +- `SAT-WiSe-25-26_[VERSION].pdf` - Versioned PDF in the release +- `Main.pdf` - Standard PDF name +- Release artifacts with 90-day retention + +## Usage + +### Triggering a Build + +Builds are triggered automatically on: +- Every push to `main` +- Every pull request + +To manually trigger a build: +1. Go to Actions tab +2. Select "Build LaTeX Document" +3. Click "Run workflow" + +### Creating a Release + +To create a new release: + +```bash +# Create an annotated tag +git tag -a v1.0.0 -m "Release version 1.0.0" + +# Push the tag to GitHub +git push origin v1.0.0 +``` + +The release workflow will automatically: +1. Build the document +2. Create a GitHub release +3. Attach the PDF with version number +4. Generate release notes from commits + +### Accessing Build Artifacts + +#### From a Regular Build: +1. Navigate to the **Actions** tab +2. Click on a workflow run +3. Scroll to **Artifacts** section +4. Download `SAT-WiSe-25-26-PDF` + +#### From a Release: +1. Navigate to **Releases** section +2. Find your release +3. Download the attached PDF files + +## Configuration + +### Environment Requirements + +The workflows use Docker to ensure consistent builds: +- Base image: `texlive/texlive:latest` +- Additional packages: `inkscape` (for SVG support) +- Build command: `make docker-build` + +### Permissions + +The release workflow requires: +- `contents: write` - To create releases and upload assets + +### Retention Policies + +- **Regular builds:** 30 days +- **Release builds:** 90 days +- **Failed build logs:** 7 days + +## Troubleshooting + +### Build Failures + +If a build fails: +1. Check the workflow run logs +2. Download the `build-logs` artifact +3. Review `Main.log` for LaTeX errors + +Common issues: +- Missing LaTeX packages +- Bibliography compilation errors +- SVG conversion problems + +### Release Creation Issues + +If a release fails: +- Ensure the tag format is correct (`v*.*.*` or `release-*`) +- Check GitHub permissions for release creation +- Verify the PDF was built successfully + +### Docker Build Issues + +The workflows use Docker Compose which: +- Automatically detects `docker-compose` vs `docker compose` +- Builds a custom image with all dependencies +- Mounts the repository as `/data` in the container + +## Maintenance + +### Updating Dependencies + +The project includes `dependabot.yml` for automatic updates: +- GitHub Actions: Weekly checks +- Docker base images: Monthly checks + +### Modifying Workflows + +When modifying workflows: +1. Test changes in a feature branch +2. Use `workflow_dispatch` for manual testing +3. Monitor the Actions tab for results + +## Best Practices + +1. **Versioning:** Use semantic versioning for tags (v1.0.0) +2. **Release Notes:** Write meaningful tag messages +3. **Artifacts:** Download important artifacts before retention expires +4. **Monitoring:** Check workflow runs regularly for failures + +## Support + +For workflow issues: +1. Check this documentation +2. Review workflow run logs +3. Open an issue in the repository +4. Contact the maintainer + +--- + +*Last updated: October 2024* \ No newline at end of file diff --git a/.github/workflows/makefile.yml b/.github/workflows/makefile.yml index 87f784b..3457bf4 100644 --- a/.github/workflows/makefile.yml +++ b/.github/workflows/makefile.yml @@ -1,17 +1,44 @@ -name: Makefile CI +name: Build LaTeX Document on: push: - branches: [ "main" ] + branches: ["main"] pull_request: - branches: [ "main" ] + branches: ["main"] + workflow_dispatch: # Allow manual triggering jobs: build: runs-on: ubuntu-latest steps: - - uses: actions/checkout@v4 + - name: Checkout repository + uses: actions/checkout@v4 - - name: Build - run: make + - name: Build document with Docker + run: make docker-build + + - name: Check if PDF was created + run: | + if [ ! -f Output/Main.pdf ]; then + echo "Error: PDF was not created" + exit 1 + fi + echo "PDF size: $(du -h Output/Main.pdf)" + + - name: Upload PDF artifact + uses: actions/upload-artifact@v4 + with: + name: SAT-WiSe-25-26-PDF + path: Output/Main.pdf + retention-days: 30 + if-no-files-found: error + + - name: Upload build logs on failure + if: failure() + uses: actions/upload-artifact@v4 + with: + name: build-logs + path: Build/*.log + retention-days: 7 + if-no-files-found: ignore diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml new file mode 100644 index 0000000..ff8a9b0 --- /dev/null +++ b/.github/workflows/release.yml @@ -0,0 +1,93 @@ +name: Create Release with PDF + +on: + push: + tags: + - 'v*.*.*' # Trigger on version tags like v1.0.0 + - 'release-*' # Trigger on release tags like release-2024-10 + +jobs: + build-and-release: + runs-on: ubuntu-latest + + permissions: + contents: write # Required for creating releases + + steps: + - name: Checkout repository + uses: actions/checkout@v4 + + - name: Extract version from tag + id: version + run: | + echo "VERSION=${GITHUB_REF#refs/tags/}" >> $GITHUB_OUTPUT + echo "DATE=$(date +'%Y-%m-%d')" >> $GITHUB_OUTPUT + + - name: Build document with Docker + run: make docker-build + + - name: Verify PDF creation + run: | + if [ ! -f Output/Main.pdf ]; then + echo "Error: PDF was not created" + exit 1 + fi + echo "PDF successfully created" + echo "Size: $(du -h Output/Main.pdf)" + + - name: Rename PDF with version + run: | + cp Output/Main.pdf "SAT-WiSe-25-26_${{ steps.version.outputs.VERSION }}.pdf" + + - name: Generate release notes + id: release_notes + run: | + cat << EOF > release_notes.md + ## SAT-WiSe-25-26 Document Release + + **Version:** ${{ steps.version.outputs.VERSION }} + **Date:** ${{ steps.version.outputs.DATE }} + + ### 📄 Document Information + - **Template:** HSRTReport LaTeX Template + - **Institution:** University of Applied Sciences Reutlingen + - **Build System:** Docker-based compilation + + ### 📦 Included Files + - \`SAT-WiSe-25-26_${{ steps.version.outputs.VERSION }}.pdf\` - The compiled document + + ### 🔧 Build Information + - Built with XeLaTeX + - Bibliography processed with Biber + - Glossaries and acronyms included + + ### 📝 Recent Changes + Please see the commit history for detailed changes. + + --- + *This release was automatically generated by GitHub Actions* + EOF + + - name: Create GitHub Release + uses: softprops/action-gh-release@v1 + with: + files: | + SAT-WiSe-25-26_${{ steps.version.outputs.VERSION }}.pdf + Output/Main.pdf + name: Release ${{ steps.version.outputs.VERSION }} + body_path: release_notes.md + draft: false + prerelease: false + generate_release_notes: true # Append auto-generated notes + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + + - name: Upload PDF as artifact (backup) + uses: actions/upload-artifact@v4 + with: + name: SAT-WiSe-25-26-Release-${{ steps.version.outputs.VERSION }} + path: | + SAT-WiSe-25-26_${{ steps.version.outputs.VERSION }}.pdf + Output/Main.pdf + retention-days: 90 + if-no-files-found: error diff --git a/Content/Chapters/03_seitenformatierung.tex b/Content/Chapters/03_seitenformatierung.tex index b234acf..9b1f582 100644 --- a/Content/Chapters/03_seitenformatierung.tex +++ b/Content/Chapters/03_seitenformatierung.tex @@ -120,10 +120,10 @@ Tabellen können an beliebiger Stelle im Text eingebaut werden. Die erste Zeile \label{tab:formatvorlagen} \begin{tabular}{|l|l|c|c|} \hline - \textbf{Formatbezeichner} & \textbf{Schrift} & \textbf{Größe} & \textbf{kursiv} \\ + \textbf{Formatbezeichner} & \textbf{Schrift} & \textbf{Größe} & \textbf{kursiv} \\ \hline - Überschrift 1 & Franklin Gothic Book & 16 & nein \\ - Eigennamen & Times New Roman & 12 & ja \\ + Überschrift 1 & DIN-Regular & \texttt{\textbackslash normalsize} & nein \\ + Eigennamen & DIN-Regular & \texttt{\textbackslash normalsize} & ja \\ \hline \end{tabular} \end{table} diff --git a/README.md b/README.md index d4dec36..44c6c89 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,9 @@ # HSRTReport LaTeX Template +[![Build LaTeX Document](https://github.com/frederik/SAT-WiSe-25-26/actions/workflows/makefile.yml/badge.svg)](https://github.com/frederik/SAT-WiSe-25-26/actions/workflows/makefile.yml) +[![GitHub release](https://img.shields.io/github/release/frederik/SAT-WiSe-25-26.svg)](https://github.com/frederik/SAT-WiSe-25-26/releases/latest) +[![License: CC BY-SA 4.0](https://img.shields.io/badge/License-CC%20BY--SA%204.0-lightgrey.svg)](https://creativecommons.org/licenses/by-sa/4.0/) + A professional LaTeX report template for academic papers and theses at the University of Applied Sciences Reutlingen (Hochschule Reutlingen). ## 📋 Table of Contents @@ -283,6 +287,53 @@ make distclean latexmk -xelatex -shell-escape -bibtex Main.tex ``` +## 🚀 CI/CD Pipeline + +### Continuous Integration + +The project includes GitHub Actions workflows for automated building and testing: + +#### Build Workflow (`makefile.yml`) +- **Triggers on:** Push to main, Pull requests +- **Actions:** + - Builds the document using Docker + - Uploads the PDF as an artifact + - Available for 30 days after build + - Build logs uploaded on failure + +#### Release Workflow (`release.yml`) +- **Triggers on:** Version tags (e.g., `v1.0.0`, `release-2024-10`) +- **Actions:** + - Creates a GitHub release + - Attaches the PDF with version number + - Generates release notes automatically + - Archives artifacts for 90 days + +### Creating a Release + +To create a new release with the PDF: + +```bash +# Tag the current commit +git tag -a v1.0.0 -m "Release version 1.0.0" + +# Push the tag to trigger the release workflow +git push origin v1.0.0 +``` + +The workflow will automatically: +1. Build the document +2. Create a GitHub release +3. Attach the PDF to the release +4. Generate release notes from commit history + +### Accessing Build Artifacts + +1. Go to the **Actions** tab in your GitHub repository +2. Select a workflow run +3. Scroll down to **Artifacts** +4. Download `SAT-WiSe-25-26-PDF` + ## 🐛 Troubleshooting ### Common Issues