VerbroederIJ Agenda Repository

Init commit

This repository contains all agenda events for the VerbroederIJ website.

Structure

• content/ - Event markdown files
• config.toml - Hugo configuration for this repository
• .gitlab-ci.yml - CI/CD pipeline configuration

Adding New Events

1. Create new markdown file in content/ directory
2. Use the following frontmatter template:

+++
language = "nl"
categorie = "agenda"
activiteit = ["Category"]
title = "Event Title"
visibleInPages = false
date = 2024-12-01T10:00:00.000Z
eindtijd = 2024-12-01T13:00:00.000Z
hideform = true

[image]
src = "images/event-image.jpeg"
+++

Event description here...

Access Control

This repository has restricted access. Contact the repository maintainer for access requests.

Integration

This repository is integrated with the main VerbroederIJ website as a submodule.

How the Automated Workflow Works

Plaats nieuwe afbeeldingen in: /images/ Plaats nieuwe activiteiten in: /content/ In de activiteit markdown file: Verwijs naar de afbeelding via onderstaand voorbeeld:

[image] src = “images/agenda/de-verbroeder-ij.jpg” +++

Belangrijk: “images/agenda” is het pad dat de hoofd website repository en build script gebruikt om de afbeelding uit de submodule te vinden en daarna te optimaliseren in JPG en WebP responsieve formaten. Let hierbij op dat op dit moment alleen JPG en PNG is ondersteund als afbeeldingbestand.

The website uses an integrated automated workflow system that manages content synchronization and deployments between multiple repositories and platforms.

Architecture Overview

The workflow involves three main components:

1. Main Website Repository (verbroederij-blocks) - Contains the Hugo site structure, themes, and static content
2. Agenda Repository (verbroederij-agenda) - Separate GitLab repository containing agenda-specific content
3. Netlify Platform - Handles website building and hosting

Automated Sync Process

1. Agenda Content Updates

When content is updated in the verbroederij-agenda repository:

• GitLab automatically triggers a pipeline in this repository
• The trigger includes metadata about the agenda changes (commit SHA, message, etc.)
• A sync job (sync_agenda_content) is automatically executed

2. GitLab CI Pipeline (.gitlab-ci.yml)

The GitLab CI pipeline consists of three stages:

Test Stage:

• Runs security scanning (SAST) to ensure code quality and security

Sync Stage:

• sync_agenda_content: Automatically triggered when agenda repository updates

  • Only runs when CI_PIPELINE_SOURCE == "trigger" and TRIGGER_SOURCE == "agenda"
  • Configures git authentication using AGENDA_SYNC_TOKEN
  • Triggers Netlify build hook to initiate deployment with fresh agenda content
  • Includes retry logic for reliability

• manual_trigger_netlify: Manual trigger for Netlify builds

  • Available for manual execution on the main branch
  • Useful for forcing deployments without agenda changes

3. Netlify Build Process (netlify-build.sh)

When Netlify receives a build trigger:

Authentication Setup:

• Configures GitLab authentication using GITLAB_TOKEN
• Sets up git to use OAuth2 authentication for GitLab URLs

Content Synchronization:

• Removes any existing agenda directory (content/nederlands/agenda)
• Clones fresh agenda content from verbroederij-agenda repository
• Verifies content integrity and reports number of agenda files found
• Creates fallback structure if cloning fails (ensures build continues)

Asset Management:

• Creates symbolic link from assets/images/agenda to agenda repository images
• Enables agenda posts to reference images using the standard Hugo image rendering system

Site Building:

• Runs Hugo build with garbage collection and minification
• Uses the configured URL for proper base path generation

Image Handling for Agenda Posts

The system includes enhanced image rendering capabilities for agenda content:

• Agenda images are stored in the verbroederij-agenda repository
• During build, images are symlinked to assets/images/agenda
• The image rendering template automatically detects agenda posts
• Agenda post images are served from the agenda subdirectory
• Fallback mechanism ensures builds continue even if agenda repository is unavailable

Configuration Requirements

GitLab Variables:

• AGENDA_SYNC_TOKEN: Authentication token for accessing agenda repository
• NETLIFY_BUILD_HOOK: Webhook URL for triggering Netlify builds

Netlify Variables:

• GITLAB_TOKEN: Token for accessing GitLab repositories during build
• URL: Base URL for the website (used in Hugo build)

Workflow Benefits

1. Automated Synchronization: Agenda updates automatically trigger website rebuilds
2. Content Separation: Agenda content is managed in a dedicated repository
3. Reliability: Includes error handling and fallback mechanisms
4. Security: Uses secure token-based authentication
5. Flexibility: Supports both automatic and manual deployment triggers
6. Performance: Efficient content cloning and asset management

Troubleshooting

Build Failures:

• Check GitLab pipeline logs for authentication issues
• Verify GITLAB_TOKEN is properly configured in Netlify
• Ensure agenda repository is accessible

Missing Agenda Content:

• Verify AGENDA_SYNC_TOKEN permissions in GitLab
• Check if agenda repository structure matches expected format
• Build will continue with fallback structure if agenda clone fails

Image Issues:

• Ensure agenda images are properly committed to agenda repository
• Verify symlink creation in build logs
• Check image paths in agenda post markdown files