XeplosionTechnologies/.forgejo

Watch

Fork

You've already forked .forgejo

Code Issues 19 Pull requests Projects 5 Releases Packages Wiki Activity Actions

Evaluate Git submodules for managed template propagation #43

New issue

Open

opened 2026-09-07 22:39:13 +00:00 by Xeplosion · 0 comments

Xeplosion commented

2026-09-07 22:39:13 +00:00

Owner

Copy link

What question are we trying to answer?

Would Git submodules materially improve the current .forgejo managed-template propagation architecture compared with the existing branch-sync system?

Specifically, could canonical workflow/script assets be referenced through a submodule without breaking Forgejo Actions discovery, managed repository creation, contributor workflows, or stack-specific template behavior?

The question is no longer whether submodules are preferable to manual copying. The current branch-sync system should be treated as the baseline architecture and submodules should only be adopted if they provide a meaningful improvement.

Why does this matter?

The current system intentionally distributes copies of canonical/shared assets into template branches and repositories.

That creates duplication, but it also provides self-contained repositories and explicit propagation behavior.

Submodules could reduce duplication, but may introduce:

nested repository dependencies;
authentication requirements;
version-pinning complexity;
checkout/setup requirements;
Forgejo Actions discovery limitations;
more difficult contributor onboarding;
failure modes where managed repositories reference unavailable canonical content.

Before changing a functioning propagation model, the tradeoff should be understood experimentally.

Scope / boundaries

Establish current baseline

Diagram the current branch-sync propagation flow.
Identify which files are shared.
Identify which files are stack-specific.
Identify where duplication is intentional.
Identify the current update/pinning model.
Record current failure and rollback characteristics.

Forgejo Actions behavior

Confirm where Forgejo requires workflow files to physically exist.
Test whether workflows can execute from a submodule path.
Test symlinks from .forgejo/workflows/ into submodule content.
Test whether Forgejo resolves such symlinks reliably.
Test runner checkout with submodules enabled.
Determine whether recursive submodule initialization is required.
Determine how manual/scheduled workflows behave.

Repository / template behavior

Test creation of a repository from a template containing a submodule.
Confirm .gitmodules behavior.
Confirm whether the new repository points to the correct canonical origin.
Evaluate behavior for private canonical repositories.
Evaluate authentication/token requirements.
Evaluate what happens if the canonical repository is unavailable.
Evaluate how a repository intentionally pins an older canonical revision.
Evaluate update behavior when canonical templates change.

Stack-specific assets

Determine whether shared and branch-specific files can coexist cleanly.
Evaluate whether stack-specific templates would still require separate branches/repos.
Determine whether submodules actually eliminate enough duplication to justify the change.
Evaluate configuration/reference assets that must remain directly in the consuming repository.

Contributor experience

Test a fresh clone.
Test clone without --recurse-submodules.
Test normal developer pull/update behavior.
Test CI checkout behavior.
Evaluate IDE/tooling behavior.
Evaluate the amount of additional documentation required.

Security / access

Determine required read credentials for private submodules.
Evaluate token/SSH-key distribution implications.
Confirm a consuming repository does not gain unnecessary write access to canonical .forgejo.
Evaluate impact on external or differently scoped managed organizations.

Comparison

Compare complexity with the current branch-sync system.
Compare propagation reliability.
Compare reproducibility/version pinning.
Compare repository portability.
Compare contributor friction.
Compare failure recovery.
Compare security implications.
Compare maintenance overhead.

Out of scope

Replacing the current sync architecture during the investigation.
Migrating all templates before a recommendation is approved.
Treating reduced duplication as sufficient justification by itself.

Definition of done

Forgejo workflow-discovery behavior has been tested or authoritatively verified.
Template-repository behavior has been tested.
Authentication/security implications are understood.
Contributor workflow has been evaluated.
The current sync system and submodule approach have been compared directly.
A proof of concept exists if the approach appears viable.
A written recommendation concludes one of:
- adopt submodules;
- adopt a hybrid model;
- retain the current branch-sync architecture.
If adoption is recommended, implementation is moved into a separate issue.

Known sources / starting points

Current .forgejo sync workflows.
sync-config.yml.
Current template branches.
Current managed template repositories.
Forgejo Actions documentation.
Git submodule documentation.
A disposable proof-of-concept repository.

Investigation checklist

The research question is specific enough to reach a conclusion
The expected output or decision is defined

Workflow lifecycle

Triage

Kind/ classification confirmed
Issue validity reviewed and appropriate Reviewed/ label assigned
Priority/ assigned when appropriate
Implementation branch referenced on the issue through Forgejo when applicable
Information requirements resolved; no Status/Needs More Info remains
Status/Needs Triage removed before leaving Triage

Backlog

Issue is confirmed valid and accepted into the project backlog

To Do

Scope and expected outcome are sufficiently defined
Known prerequisites, dependencies, and required decisions are resolved or understood
Work has been deliberately selected as upcoming work

In Progress

Assignee or active owner identified when appropriate
Forgejo timer started when time tracking provides meaningful value
Relevant implementation, research, or work notes recorded as needed
Forgejo timer stopped when active work ends, pauses, or becomes blocked

Review Gate

Review requirement assessed based on complexity, criticality, reversibility, and impact
If review is required: moved to In Review and appropriate testing / validation performed
If review is required: review comment records what was reviewed, how it was validated, findings, and outcome
If review is not required: rationale is evident from the low-risk nature of the change

Completed

Acceptance criteria / intended outcome satisfied
Related PRs, commits, documentation, or external changes linked where applicable
Resolution is documented by a linked PR that closes the issue, or by a final issue comment explaining what changed, how it was resolved, and how it was verified
Follow-up work split into separate issues where appropriate
Any Forgejo timer is stopped and recorded time is final
Issue moved to Completed and closed

### What question are we trying to answer? Would Git submodules materially improve the current `.forgejo` managed-template propagation architecture compared with the existing branch-sync system? Specifically, could canonical workflow/script assets be referenced through a submodule without breaking Forgejo Actions discovery, managed repository creation, contributor workflows, or stack-specific template behavior? The question is no longer whether submodules are preferable to manual copying. The current branch-sync system should be treated as the baseline architecture and submodules should only be adopted if they provide a meaningful improvement. ### Why does this matter? The current system intentionally distributes copies of canonical/shared assets into template branches and repositories. That creates duplication, but it also provides self-contained repositories and explicit propagation behavior. Submodules could reduce duplication, but may introduce: * nested repository dependencies; * authentication requirements; * version-pinning complexity; * checkout/setup requirements; * Forgejo Actions discovery limitations; * more difficult contributor onboarding; * failure modes where managed repositories reference unavailable canonical content. Before changing a functioning propagation model, the tradeoff should be understood experimentally. ### Scope / boundaries ### Establish current baseline * [ ] Diagram the current branch-sync propagation flow. * [ ] Identify which files are shared. * [ ] Identify which files are stack-specific. * [ ] Identify where duplication is intentional. * [ ] Identify the current update/pinning model. * [ ] Record current failure and rollback characteristics. ### Forgejo Actions behavior * [ ] Confirm where Forgejo requires workflow files to physically exist. * [ ] Test whether workflows can execute from a submodule path. * [ ] Test symlinks from `.forgejo/workflows/` into submodule content. * [ ] Test whether Forgejo resolves such symlinks reliably. * [ ] Test runner checkout with submodules enabled. * [ ] Determine whether recursive submodule initialization is required. * [ ] Determine how manual/scheduled workflows behave. ### Repository / template behavior * [ ] Test creation of a repository from a template containing a submodule. * [ ] Confirm `.gitmodules` behavior. * [ ] Confirm whether the new repository points to the correct canonical origin. * [ ] Evaluate behavior for private canonical repositories. * [ ] Evaluate authentication/token requirements. * [ ] Evaluate what happens if the canonical repository is unavailable. * [ ] Evaluate how a repository intentionally pins an older canonical revision. * [ ] Evaluate update behavior when canonical templates change. ### Stack-specific assets * [ ] Determine whether shared and branch-specific files can coexist cleanly. * [ ] Evaluate whether stack-specific templates would still require separate branches/repos. * [ ] Determine whether submodules actually eliminate enough duplication to justify the change. * [ ] Evaluate configuration/reference assets that must remain directly in the consuming repository. ### Contributor experience * [ ] Test a fresh clone. * [ ] Test clone without `--recurse-submodules`. * [ ] Test normal developer pull/update behavior. * [ ] Test CI checkout behavior. * [ ] Evaluate IDE/tooling behavior. * [ ] Evaluate the amount of additional documentation required. ### Security / access * [ ] Determine required read credentials for private submodules. * [ ] Evaluate token/SSH-key distribution implications. * [ ] Confirm a consuming repository does not gain unnecessary write access to canonical `.forgejo`. * [ ] Evaluate impact on external or differently scoped managed organizations. ### Comparison * [ ] Compare complexity with the current branch-sync system. * [ ] Compare propagation reliability. * [ ] Compare reproducibility/version pinning. * [ ] Compare repository portability. * [ ] Compare contributor friction. * [ ] Compare failure recovery. * [ ] Compare security implications. * [ ] Compare maintenance overhead. ## Out of scope * Replacing the current sync architecture during the investigation. * Migrating all templates before a recommendation is approved. * Treating reduced duplication as sufficient justification by itself. ### Definition of done * [ ] Forgejo workflow-discovery behavior has been tested or authoritatively verified. * [ ] Template-repository behavior has been tested. * [ ] Authentication/security implications are understood. * [ ] Contributor workflow has been evaluated. * [ ] The current sync system and submodule approach have been compared directly. * [ ] A proof of concept exists if the approach appears viable. * [ ] A written recommendation concludes one of: * adopt submodules; * adopt a hybrid model; * retain the current branch-sync architecture. * [ ] If adoption is recommended, implementation is moved into a separate issue. ### Known sources / starting points * Current `.forgejo` sync workflows. * `sync-config.yml`. * Current template branches. * Current managed template repositories. * Forgejo Actions documentation. * Git submodule documentation. * A disposable proof-of-concept repository. ### Investigation checklist - [x] The research question is specific enough to reach a conclusion - [x] The expected output or decision is defined ### Workflow lifecycle ### Triage - [x] `Kind/` classification confirmed - [x] Issue validity reviewed and appropriate `Reviewed/` label assigned - [x] `Priority/` assigned when appropriate - [x] Implementation branch referenced on the issue through Forgejo when applicable - [x] Information requirements resolved; no `Status/Needs More Info` remains - [x] `Status/Needs Triage` removed before leaving Triage ### Backlog - [x] Issue is confirmed valid and accepted into the project backlog ### To Do - [ ] Scope and expected outcome are sufficiently defined - [ ] Known prerequisites, dependencies, and required decisions are resolved or understood - [ ] Work has been deliberately selected as upcoming work ### In Progress - [ ] Assignee or active owner identified when appropriate - [ ] Forgejo timer started when time tracking provides meaningful value - [ ] Relevant implementation, research, or work notes recorded as needed - [ ] Forgejo timer stopped when active work ends, pauses, or becomes blocked ### Review Gate - [ ] Review requirement assessed based on complexity, criticality, reversibility, and impact - [ ] If review is required: moved to **In Review** and appropriate testing / validation performed - [ ] If review is required: review comment records what was reviewed, how it was validated, findings, and outcome - [ ] If review is not required: rationale is evident from the low-risk nature of the change ### Completed - [ ] Acceptance criteria / intended outcome satisfied - [ ] Related PRs, commits, documentation, or external changes linked where applicable - [ ] Resolution is documented by a linked PR that closes the issue, or by a final issue comment explaining what changed, how it was resolved, and how it was verified - [ ] Follow-up work split into separate issues where appropriate - [ ] Any Forgejo timer is stopped and recorded time is final - [ ] Issue moved to **Completed** and closed

Xeplosion added the

Rows
Columns