GitHub Flow Synchronization
Relevant source files
The following files were used as context for generating this wiki page:
GitHub Flow Synchronization is a mechanism used by the swimctl project to manage and synchronize Node-RED flow definitions between a remote GitHub repository and the local Kubernetes-based swimming pool automation controller. This system ensures that the automation logic is version-controlled and can be deployed or updated consistently across the environment.
The synchronization process relies on a Git-based init container for initial deployment and a custom Git hook for pushing local changes back to the remote repository. This allows for a bi-directional or at least a repository-driven workflow where the source of truth for flows resides in GitHub.
Sources: values.yml:45-56, values.yml:85-98, README.md:1-5
Synchronization Architecture
The synchronization architecture is divided into two primary phases: the initialization phase (pulling logic) and the post-commit phase (pushing updates).
Initialization Phase
When the Node-RED pod starts, an init container named clone-repo executes. This container uses an Alpine-based Git image to clone the remote repository containing the flows (swimctl-flows.git) into the /data/projects directory. It checkouts the main branch (or a specified GIT_VERSION) to ensure the local environment matches the remote state.
The diagram above illustrates the sequence of operations performed by the init container before the main Node-RED application starts.
Sources: values.yml:85-105
Git Hook and Automation
To facilitate changes made within the local environment, the system automatically configures a .git/hooks/post-commit script. When a commit is made locally, this hook captures the latest commit hash, generates a patch, and triggers a GitHub Actions workflow (apply-patch.yml) using a repository dispatch event.
Sources: values.yml:108-121
Configuration and Secrets
The synchronization system requires specific environment variables and secrets to authenticate with GitHub and identify the target repository.
| Environment Variable | Description | Source |
|---|---|---|
GITHUB_TOKEN_FLOWS | Bearer token for GitHub API authentication. | values.yml:51 |
GITHUB_OWNER_FLOWS | The GitHub user or organization owning the flows repository. | values.yml:56 |
GITHUB_REPO_NAME_FLOWS | The name of the specific flows repository. | values.yml:61 |
NODE_RED_ENABLE_PROJECTS | Enables the project feature in Node-RED (set to 'true'). | values.yml:43 |
NODE_RED_ACTIVE_PROJECT | Specifies 'swimctl-flows' as the active project. | values.yml:46 |
These values are populated via a Kubernetes secret named swimctl, which is created during the installation process.
Sources: values.yml:41-65, README.md:46-52
Data Persistence and Projects
The integration uses specific volume mounts to ensure Node-RED recognizes the synchronized Git repository as a valid project.
Project Settings
The node-red-projects-settings ConfigMap defines the project structure, specifically setting swimctl-flows as the active project and disabling credentialSecret within the project context.
{
"projects": {
"swimctl-flows": {
"credentialSecret": false
}
},
"activeProject": "swimctl-flows"
}
Sources: configMaps.yaml:33-41
Volume Mapping
The project configuration is mounted into the container at /data/.config.projects.json. This links the Kubernetes configuration directly to Node-RED's internal project management system.
| Name | Mount Path | SubPath |
|---|---|---|
node-red-projects-settings | /data/.config.projects.json | .config.projects.json |
data | /data | N/A |
Sources: values.yml:71-82, values.yml:123-125
Local Hook Logic Implementation
The post-commit hook is the core of the outbound synchronization. It performs the following steps:
- Retrieves the HEAD commit hash.
- Formats the last commit as a patch.
- Base64 encodes the patch content to ensure safe transmission via JSON.
- Dispatches a POST request to the GitHub API endpoint for repository dispatches.
#!/bin/bash
commit_hash=$(git rev-parse HEAD)
patch_content=$(git format-patch -1 $commit_hash --stdout | base64 | awk '{printf "%s\\n", $0}' )
url="https://api.github.com/repos/$GITHUB_OWNER_FLOWS/$GITHUB_REPO_NAME_FLOWS/actions/workflows/apply-patch.yml/dispatches"
curl -X POST \
-H "Accept: application/vnd.github.v3+json" \
-H "Authorization: Bearer $GITHUB_TOKEN_FLOWS" \
"$url" \
-d "{\"ref\":\"main\", \"inputs\": {\"patchContent\": \"$patch_content\"}}"
Sources: values.yml:110-120
Summary
GitHub Flow Synchronization in swimctl creates a bridge between local Node-RED development and remote version control. By utilizing Kubernetes init containers and Git hooks, the system automates the deployment of flows and provides a path for pushing local updates back to GitHub via automated workflows.
Sources: values.yml:85-121, README.md:46-52