# HyperTwist Forgejo/Woodpecker Bootstrap And First Push

Last updated: `2026-04-25` (`Europe/Berlin`)

Purpose:

- give HyperTwist a product-specific CI/CD onboarding note without copying ScriptoriumAI's live sensitive VPS runbook wholesale
- make the repository ready for first remote creation, first commit, first push, and first Woodpecker activation
- define the minimum CI chain now, while leaving production deployment details deferred until a real HyperTwist host and secret set exist

Reference source:

- `C:\HyperTwist\docs\refs\FORGEJO_WOODPECKER_VPS_A_TO_Z_SENSITIVE_RUNBOOK.md`

## Current HyperTwist state

Verified on `2026-04-25`:

- local git repo exists:
  - `C:\HyperTwist\.git`
- no git remote is configured yet
- no HyperTwist Woodpecker config existed before this bootstrap pass
- the working tree is still effectively an initial large untracked tree

Implication:

- HyperTwist is version-controlled locally
- but it has not yet been inserted into a remote Forgejo + Woodpecker chain

## What is reusable from the ScriptoriumAI runbook

Reusable patterns:

- Forgejo as the canonical remote source
- Woodpecker as the push-triggered CI control plane
- builder-label separation from ops-only agents
- `skip_clone: true` plus explicit `git clone` when the environment needs deterministic checkout behavior
- keeping bootstrap CI separate from later deploy workflows
- documenting secrets by class, not by assumption

## What is not reusable as-is

Do not copy these directly into HyperTwist:

- ScriptoriumAI domains
- ScriptoriumAI secrets
- ScriptoriumAI VPS paths
- ScriptoriumAI deploy scripts
- ScriptoriumAI production-host assumptions
- ScriptoriumAI repo name or owner slug

HyperTwist needs its own:

- Forgejo repo path
- Woodpecker repo activation
- builder labels
- deployment target
- SSH secrets
- production smoke path

## Current recommended insertion point

Use a two-step chain first.

Step 1:

- source control bootstrap
- remote creation
- first commit
- first push
- bootstrap CI only

Step 2 later:

- production deployment workflow
- deploy secrets
- smoke checks
- rollback procedure

This is the correct order because HyperTwist does not yet have a documented production host or secret set.

## Minimum first-time chain

The current recommended chain is:

1. create the HyperTwist repo in Forgejo
2. add `origin` locally
3. create the first intentional commit
4. push `main`
5. enable the repo in Woodpecker
6. let the bootstrap workflow validate the repository shape
7. only after that, add deploy-specific workflows and secrets

## Recommended Forgejo repo shape

Suggested placeholder until the final namespace is chosen:

- owner: the real HyperTwist Forgejo namespace
- repo: `hypertwist`

Canonical remote pattern:

```text
git@<forgejo-host>:<owner>/hypertwist.git
```

HTTPS clone pattern if needed:

```text
https://<forgejo-host>/<owner>/hypertwist.git
```

## First local commands

After the Forgejo repo exists, use:

```powershell
git -C C:\HyperTwist remote add origin git@<forgejo-host>:<owner>/hypertwist.git
git -C C:\HyperTwist branch -M main
git -C C:\HyperTwist add <scoped-paths>
git -C C:\HyperTwist commit -m "Bootstrap HyperTwist repo and CI"
git -C C:\HyperTwist push -u origin main
```

Important scoping rule:

- do not blindly commit the entire current working tree without an explicit first-commit scope decision
- the repo currently contains research material, mirrors, docs, Unreal work, and auxiliary files in one large untracked tree
- the first commit should be intentional

## Recommended initial tracked set

The current recommended first commit scope is:

- `C:\HyperTwist\.gitattributes`
- `C:\HyperTwist\.gitignore`
- `C:\HyperTwist\.woodpecker\hypertwist-bootstrap.yml`
- `C:\HyperTwist\docs\**` except `C:\HyperTwist\docs\refs\**`
- `C:\HyperTwist\scripts\**`
- `C:\HyperTwist\logo\HyperTwist logo with 3D symbol.png`
- `C:\HyperTwist\UnrealHyperTwist\UnrealHyperTwist.uproject`
- `C:\HyperTwist\UnrealHyperTwist\Config\*.ini`
- `C:\HyperTwist\UnrealHyperTwist\Source\UnrealHyperTwist\**`

This keeps the initial repository honest:

- first-party Unreal code is tracked
- product-specific CI bootstrap is tracked
- non-sensitive docs and workspace/bootstrap scripts are tracked
- the primary product logo is tracked
- external mirrors, bulky archives, and sensitive refs stay out

## Recommended initial exclusions

The following should stay out of the first commit unless separately curated later:

- `C:\HyperTwist\docs\refs\**`
- `C:\HyperTwist\mirrors\**`
- `C:\HyperTwist\zippedreposource\**`
- the root archive and website-dump folders
- `C:\HyperTwist\Schläfli symbol\**`
- root one-off research/reference PDFs, WEBPs, and prompt files
- `C:\HyperTwist\logo\Miscellaneous\**`
- `C:\HyperTwist\UnrealHyperTwist\Plugins\**`
- `C:\HyperTwist\UnrealHyperTwist\Binaries\**`
- `C:\HyperTwist\UnrealHyperTwist\DerivedDataCache\**`
- `C:\HyperTwist\UnrealHyperTwist\Intermediate\**`
- `C:\HyperTwist\UnrealHyperTwist\Saved\**`
- generated Visual Studio solutions and user files

This is a bootstrap boundary, not a claim that the excluded material is permanently unwanted.

## Bootstrap CI scope

The initial Woodpecker workflow added in this pass is bootstrap-only.

It proves:

- Forgejo webhook -> Woodpecker pipeline trigger
- checkout works
- the expected HyperTwist tree exists
- key product folders are present

It does **not** yet prove:

- Unreal compilation
- packaging
- deployment
- production smoke

## Added bootstrap workflow

New workflow path:

- `C:\HyperTwist\.woodpecker\hypertwist-bootstrap.yml`

Current purpose:

- explicit checkout using `CI_REPO_CLONE_URL`
- verify:
  - `.git` checkout happened
  - `UnrealHyperTwist/UnrealHyperTwist.uproject` exists
  - `UnrealHyperTwist/Source/UnrealHyperTwist` exists
  - `docs` exists

Why this workflow is intentionally narrow:

- HyperTwist is not yet ready for honest deployment automation
- the Unreal project currently has upstream plugin-rule collisions that block full editor-build verification
- fake deploy stages would create noise, not progress

## Woodpecker activation sequence

Once the Forgejo repo is pushed:

1. open Woodpecker
2. sync repos if needed
3. enable the HyperTwist repo
4. confirm the default branch is `main`
5. trigger the bootstrap pipeline manually if the first push did not auto-run

## Builder labeling recommendation

Keep the same deployment discipline used elsewhere:

- bootstrap/build agents should have builder labels
- ops-only agents should not accidentally pick up repo builds

Suggested initial labels for HyperTwist bootstrap:

- `role=builder`
- `backend=local`

That matches the new bootstrap workflow and stays compatible with a future external builder host.

## What must be decided before production deployment is added

Before adding deploy steps, decide:

1. Forgejo host and owner namespace
2. Woodpecker builder host
3. HyperTwist production host
4. deploy path
5. SSH identity and known-hosts policy
6. smoke endpoint or equivalent deployment-health check
7. whether deployment is:
   - Windows-hosted
   - Linux/VPS-hosted
   - artifact-only in the first phase

## Current recommendation

Do not add a production deploy workflow yet.

Instead:

- get the repo remotely created
- get the first intentional commit pushed
- get bootstrap CI green
- then add a second document for:
  - HyperTwist production topology
  - deploy secrets
  - deploy pipeline
  - smoke and rollback

## Immediate next operational move

After this document lands, the next operational task should be:

1. choose the real Forgejo namespace and repo URL
2. add `origin`
3. decide first-commit scope
4. stage and commit that scope
5. push `main`
6. enable the repo in Woodpecker

At that point HyperTwist will be inserted into the version-control and CI chain honestly, without pretending the production deployment layer is already settled.

If the remote URL is still unknown, the safe order is:

1. make the initial scoped local commit on `main`
2. wait for the real Forgejo repo path
3. add `origin`
4. push that already-scoped history
