chore: Workflow & Docs Updates (#332)

.github/renovate.json

@@ -7,7 +7,7 @@
     "dependencies"
   ],
   "draftPR": true,
-  "baseBranches": ["main"],
+  "baseBranches": ["staging"],
   "rebaseWhen": "conflicted",
   "prHourlyLimit": 10,
   "packageRules": [

.github/workflows/build_docker.yml

@@ -86,8 +86,8 @@ jobs:
         with:
           images: ${{ matrix.image }}
           tags: |
-            # Apply 'latest' tag for default branch
-            type=raw,value=latest,enable={{is_default_branch}}
+            # Apply 'latest' tag if the branch is main
+            type=raw,value=latest,enable=${{ github.ref == format('refs/heads/{0}', 'main') }}
             type=ref,event=branch
             type=ref,event=pr
             type=sha

.github/workflows/docs.yml

@@ -7,7 +7,7 @@ on:
       - '.github/workflows/docs.yml'
   push:
     branches:
-      - main
+      - staging
     paths:
       - 'docs/**'
       - '.github/workflows/docs.yml'
@@ -35,7 +35,7 @@ jobs:
         with:
           path: docs/_build/dirhtml/
   deploy:
-    if: github.ref == 'refs/heads/main'
+    if: github.ref == 'refs/heads/staging'
     environment:
       name: github-pages
       url: "https://ls1intum.github.io/Helios/"

.github/workflows/enforce-staging-source-branch.yml

@@ -0,0 +1,17 @@
+name: Check pull request source branch
+on:
+  pull_request_target:
+    types:
+      - opened
+      - reopened
+      - synchronize
+jobs:
+  check-branches:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check branches
+        run: |
+          if [ ${{ github.head_ref }} != "staging" ] && [ ${{ github.base_ref }} == "main" ]; then
+            echo "::error::Merge requests to main branch are only allowed from staging branch."
+            exit 1
+          fi

.github/workflows/flyway-validate.yml

@@ -2,7 +2,7 @@ name: Flyway Validation
 
 on:
   pull_request:
-    branches: [main]
+    branches: [staging]
   workflow_call: {}
 
 env:

.github/workflows/pr-title-validation.yml

@@ -1,7 +1,7 @@
 name: Chore
 on:
   pull_request:
-    branches: [main]
+    branches: [staging]
     types: [opened, reopened, edited, synchronize]
 
 concurrency:

.github/workflows/prod.yml

@@ -3,6 +3,21 @@ name: Build and Deploy to Prod
 on:
   push:
     branches: [main]
+    paths-ignore:
+      - '.codacy.yaml'
+      - '.env.example'
+      - '.gitignore'
+      - 'compose.prod.yaml'
+      - 'compose.yaml'
+      - 'helios-example-realm.json'
+      - 'LICENSE'
+      - 'nginx.conf'
+      - 'openapitools.json'
+      - 'README.md'
+      - '.github/**'
+      - '.vscode/**'
+      - 'docs/**'
+      - 'keycloakify/**'
 
 jobs:
   validate-flyway:

.github/workflows/test.yml

@@ -1,7 +1,7 @@
 name: Unit and Integration Tests
 on:
   pull_request:
-    branches: [main]
+    branches: [staging]
     types: [opened, reopened, edited, synchronize]
 
 jobs:

.github/workflows/validate-openapi.yml

@@ -2,7 +2,7 @@ name: Validate OpenAPI Spec and Generated Client Code
 
 on:
   pull_request:
-    branches: [main]
+    branches: [staging]
     types: [opened, reopened, edited, synchronize]
 
 jobs:

client/README.md

@@ -108,3 +108,4 @@ Angular CLI does not come with an end-to-end testing framework by default. You c
 ## Additional Resources
 
 For more information on using the Angular CLI, including detailed command references, visit the [Angular CLI Overview and Command Reference](https://angular.dev/tools/cli) page.
+

docs/index.rst

@@ -15,6 +15,13 @@ Introduction
 
 The Artemis open-source project relies on GitHub Actions for its CI/CD workflows but faces challenges such as complex workflows, lack of user-friendly deployment management, and limited test analytics. This project aims to enhance the CI/CD capabilities of Artemis by developing a centralized web application that integrates with GitHub Actions. The proposed solution will provide a streamlined platform for managing deployments, environment tracking, and test analytics, accessible through an intuitive interface.
 
+.. toctree::
+  :caption: User Guide
+  :includehidden:
+  :maxdepth: 3
+
+  user_guide/deployments/testserver
+
 .. toctree::
   :caption: Contributor Guide
   :includehidden:

docs/user_guide/deployments/testserver.rst

@@ -0,0 +1,111 @@
+=================
+Helios User Guide
+=================
+
+Overview
+--------
+Helios is a deployment management tool that simplifies the process of deploying pull requests and branches to test environments. This guide walks you through the basic deployment workflow.
+
+Prerequisites
+--------------
+- GitHub account with access to the repository
+- Proper permissions to deploy
+- Available test environment
+
+Deployment Workflow
+--------------------
+
+
+1. Repository Selection
+~~~~~~~~~~~~~~~~~~~~~~~~
+Select the repository you want to deploy from the main dashboard.
+
+.. figure:: ../../images/user_guide/1-select-repo.png
+   :height: 512px
+   :alt: Repository selection screen
+
+
+2. Authentication
+~~~~~~~~~~~~~~~~~~
+Log in with your GitHub credentials.
+
+.. figure:: ../../images/user_guide/2-login.png
+   :height: 512px
+   :alt: Login with GitHub
+
+
+.. figure:: ../../images/user_guide/3-login-gh.png
+   :height: 512px
+   :alt: GitHub authentication
+
+
+3. Pull Request Selection
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+Choose the pull request or branch you want to deploy.
+
+.. figure:: ../../images/user_guide/4-open-pr.png
+   :height: 512px
+   :alt: Pull request details screen
+
+
+4. Deployment Initiation
+~~~~~~~~~~~~~~~~~~~~~~~~~
+Click the deploy button to start the deployment process.
+
+.. figure:: ../../images/user_guide/5-deploy.png
+   :height: 512px
+   :alt: Deploy button and options
+
+
+
+The deployment enters a pending state while resources are being allocated.
+
+.. figure:: ../../images/user_guide/6-deployment-pending.png
+   :height: 512px
+   :alt: Deployment pending status
+
+
+The deployment moves to the in-progress state during active deployment.
+
+.. figure:: ../../images/user_guide/7-deployment-in-progress.png
+   :height: 512px
+   :alt: Deployment progress status
+
+5. Unlock the test environment once you finish testing.
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. figure:: ../../images/user_guide/8-unlock.png
+   :height: 512px
+   :alt: Unlock test environment
+
+
+Troubleshooting
+----------------
+
+Manual Deployment Fallback
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+⚠️ **Warning**: Manual workflow deployment should be used only as a last resort as it may conflict with Helios environment locking.
+
+If Helios deployment fails, you can use the GitHub workflow as a fallback:
+
+Access the workflow at:
+   https://github.com/ls1intum/Artemis/actions/workflows/testserver-deployment.yml
+
+.. figure:: ../../images/user_guide/github-deployment.png
+   :height: 512px
+   :alt: GitHub deployment workflow
+
+Required Inputs
+*****************
+- **Use workflow from**: Select your target branch
+- **Which branch to deploy**: Again, select your target branch
+- **Which environment to deploy**: Use format ``artemis-test7.artemis.cit.tum.de``
+- **Username** (optional): Your GitHub username
+
+
+Support
+-------
+For assistance:
+
+- Join the Helios Support Slack channel https://ls1tum.slack.com/archives/C08BPLNT8FL
+- Report a new issue if you encounter a bug or need help https://github.com/ls1intum/Helios/issues/new/choose