Add Android forensics, IOC threat-intel DB, Compose companion; scrub secrets from configs
This commit is contained in:
SsSnake
256
autarch_companion/gitea_module.md
Normal file
256
autarch_companion/gitea_module.md
Normal file
@@ -0,0 +1,256 @@
|
||||
# Linking Archon as a Git Submodule of AUTARCH
|
||||
|
||||
This guide walks through setting up Archon (the Android companion app) as a git submodule inside the AUTARCH repository, hosted on a self-hosted Gitea instance.
|
||||
|
||||
**Assumed URLs:**
|
||||
- AUTARCH: `https://gitea.example.com/you/autarch`
|
||||
- Archon: `https://gitea.example.com/you/archon`
|
||||
|
||||
---
|
||||
|
||||
## 1. Initial Setup — Create Both Repos on Gitea
|
||||
|
||||
### Create the repos on Gitea
|
||||
|
||||
Log into your Gitea instance and create two repositories:
|
||||
|
||||
1. Go to `https://gitea.example.com` → **+** → **New Repository**
|
||||
2. Create `autarch` (do not initialize with README if you already have local files)
|
||||
3. Repeat for `archon`
|
||||
|
||||
### Push AUTARCH
|
||||
|
||||
```bash
|
||||
cd /path/to/autarch
|
||||
git init # if not already a git repo
|
||||
git remote add origin https://gitea.example.com/you/autarch.git
|
||||
git add .
|
||||
git commit -m "Initial commit"
|
||||
git push -u origin main
|
||||
```
|
||||
|
||||
### Push Archon
|
||||
|
||||
```bash
|
||||
cd /path/to/archon
|
||||
git init
|
||||
git remote add origin https://gitea.example.com/you/archon.git
|
||||
git add .
|
||||
git commit -m "Initial commit"
|
||||
git push -u origin main
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. Add Archon as a Submodule
|
||||
|
||||
From the **AUTARCH repository root**, run:
|
||||
|
||||
```bash
|
||||
cd /path/to/autarch
|
||||
git submodule add https://gitea.example.com/you/archon.git Archon
|
||||
```
|
||||
|
||||
This does three things:
|
||||
- Clones the Archon repo into `autarch/Archon/`
|
||||
- Creates (or updates) `.gitmodules` in the AUTARCH root
|
||||
- Stages both `.gitmodules` and the new `Archon` directory pointer
|
||||
|
||||
If you prefer SSH instead of HTTPS:
|
||||
|
||||
```bash
|
||||
git submodule add git@gitea.example.com:you/archon.git Archon
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. Commit the Submodule Reference
|
||||
|
||||
After adding the submodule, two things are staged:
|
||||
|
||||
- `.gitmodules` — a config file mapping the submodule path to its URL
|
||||
- `Archon` — not the Archon files themselves, but a **pointer** (a specific commit hash) to the Archon repo
|
||||
|
||||
Commit both:
|
||||
|
||||
```bash
|
||||
git status
|
||||
# On branch main
|
||||
# Changes to be committed:
|
||||
# new file: .gitmodules
|
||||
# new file: Archon
|
||||
|
||||
git commit -m "Add Archon as git submodule"
|
||||
git push origin main
|
||||
```
|
||||
|
||||
AUTARCH's repo now contains a reference to a specific commit in Archon — not the Archon files directly. This is intentional: submodules are pinned to a commit, not a branch.
|
||||
|
||||
---
|
||||
|
||||
## 4. `.gitmodules` Example
|
||||
|
||||
After running `git submodule add`, your `.gitmodules` file will look like this:
|
||||
|
||||
```ini
|
||||
[submodule "Archon"]
|
||||
path = Archon
|
||||
url = https://gitea.example.com/you/archon.git
|
||||
```
|
||||
|
||||
If you want to track a specific branch (optional, see pitfalls):
|
||||
|
||||
```ini
|
||||
[submodule "Archon"]
|
||||
path = Archon
|
||||
url = https://gitea.example.com/you/archon.git
|
||||
branch = main
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. Cloning AUTARCH with Archon
|
||||
|
||||
### Option A — Clone everything at once (recommended)
|
||||
|
||||
```bash
|
||||
git clone --recurse-submodules https://gitea.example.com/you/autarch.git
|
||||
```
|
||||
|
||||
This clones AUTARCH and immediately initializes and checks out Archon at the pinned commit.
|
||||
|
||||
### Option B — Clone AUTARCH first, pull Archon later
|
||||
|
||||
```bash
|
||||
git clone https://gitea.example.com/you/autarch.git
|
||||
cd autarch
|
||||
git submodule update --init
|
||||
```
|
||||
|
||||
`--init` is needed the first time because the submodule isn't initialized yet. After that, use `git submodule update` without `--init`.
|
||||
|
||||
To also pull nested submodules (if Archon ever gains its own submodules):
|
||||
|
||||
```bash
|
||||
git submodule update --init --recursive
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. Updating Archon to a Newer Commit
|
||||
|
||||
The submodule is pinned to a specific commit. To move AUTARCH's pointer to a newer Archon commit:
|
||||
|
||||
```bash
|
||||
# Step into the submodule
|
||||
cd Archon
|
||||
git checkout main
|
||||
git pull origin main
|
||||
|
||||
# Step back out to AUTARCH
|
||||
cd ..
|
||||
|
||||
# The submodule pointer has changed — stage and commit it
|
||||
git add Archon
|
||||
git commit -m "Update Archon submodule to latest"
|
||||
git push origin main
|
||||
```
|
||||
|
||||
After this, anyone who runs `git submodule update` in their AUTARCH clone will get the newer Archon commit.
|
||||
|
||||
---
|
||||
|
||||
## 7. Gitea UI — How Submodules Are Displayed
|
||||
|
||||
When you browse to `https://gitea.example.com/you/autarch` in the Gitea web UI, the `Archon` directory will appear in the file list with a special icon and a label like:
|
||||
|
||||
```
|
||||
Archon @ a3f92c1
|
||||
```
|
||||
|
||||
The `@ a3f92c1` is a clickable link that takes you directly to that commit in the `archon` repository. Gitea resolves the link automatically as long as both repos are on the same Gitea instance and the URL in `.gitmodules` matches.
|
||||
|
||||
If the submodule URL points to an external host (e.g., GitHub), Gitea will still show the `@ hash` label but the link will point to the external URL.
|
||||
|
||||
---
|
||||
|
||||
## 8. CI/CD — Checking Out Submodules in Gitea Actions
|
||||
|
||||
If you use Gitea Actions (workflow syntax is identical to GitHub Actions), the default `actions/checkout` step does **not** pull submodules. Add `submodules: true` to fix this:
|
||||
|
||||
```yaml
|
||||
name: AUTARCH CI
|
||||
|
||||
on: [push, pull_request]
|
||||
|
||||
jobs:
|
||||
build:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- name: Checkout AUTARCH with submodules
|
||||
uses: actions/checkout@v4
|
||||
with:
|
||||
submodules: true # fetches Archon at the pinned commit
|
||||
# submodules: recursive # use this if submodules have their own submodules
|
||||
|
||||
- name: Build
|
||||
run: make build
|
||||
```
|
||||
|
||||
For private submodules on the same Gitea instance, you may need to configure an SSH key or access token in the workflow secrets and set the submodule URL to use SSH.
|
||||
|
||||
---
|
||||
|
||||
## 9. Common Pitfalls
|
||||
|
||||
### Detached HEAD in the submodule
|
||||
|
||||
When you run `git submodule update`, the submodule is checked out at a specific commit — not a branch. This is called a **detached HEAD** state. If you `cd Archon` and make commits while in detached HEAD, those commits are not on any branch and can be lost.
|
||||
|
||||
Fix: before making changes inside the submodule, always check out a branch first:
|
||||
|
||||
```bash
|
||||
cd Archon
|
||||
git checkout main
|
||||
# now make changes, commit, push
|
||||
```
|
||||
|
||||
### Forgot to commit after updating the submodule
|
||||
|
||||
Running `cd Archon && git pull` updates the Archon files locally but does **not** automatically update AUTARCH's pointer to the new commit. You must come back to the AUTARCH root and commit:
|
||||
|
||||
```bash
|
||||
cd ..
|
||||
git add Archon
|
||||
git commit -m "Update Archon submodule"
|
||||
```
|
||||
|
||||
If you push AUTARCH without doing this, the pointer still points to the old Archon commit and collaborators won't get the update.
|
||||
|
||||
### SSH vs HTTPS
|
||||
|
||||
Choose one scheme and be consistent. If your team uses SSH keys for Gitea authentication, use the SSH URL in `.gitmodules`:
|
||||
|
||||
```ini
|
||||
url = git@gitea.example.com:you/archon.git
|
||||
```
|
||||
|
||||
If you use HTTPS with a token, use the HTTPS URL. Mixing them causes authentication failures for people whose environment only has one configured.
|
||||
|
||||
You can override the URL locally (without touching `.gitmodules`) using:
|
||||
|
||||
```bash
|
||||
git config submodule.Archon.url git@gitea.example.com:you/archon.git
|
||||
```
|
||||
|
||||
This writes to `.git/config` and is not committed, so it only affects your local clone.
|
||||
|
||||
### Cloning without `--recurse-submodules`
|
||||
|
||||
If someone clones AUTARCH normally and then tries to build, the `Archon/` directory will exist but be **empty**. They need to run:
|
||||
|
||||
```bash
|
||||
git submodule update --init
|
||||
```
|
||||
|
||||
Document this in your project README so contributors know to expect it.
|
||||
Reference in New Issue
Block a user