Git Workflow » History » Revision 9
Revision 8 (Redmine Admin, 11/03/2026 08:36 AM) → Revision 9/11 (Redmine Admin, 11/03/2026 10:42 AM)
*Chapter 3.1 of the dmz-web documentation · headings are numbered like the cheat sheets · index: [[Wiki]]*
{{>toc}}
Repos are bare, owned by the restricted host user `git` (git-shell) — the one
deliberate exception to the no-host-packages rule. Redmine only *reads* them.
**Who does what — this is the part that causes confusion, so read it first:**
| Step | Run as | Why |
|----------------------------------------|-----------------|------------------------------------------------------------|
| create bare repo, ACL, SELinux label | **root** | `/srv/git` is root/git territory |
| `git add` / `git commit` in a working copy | **owner user** (websvcmaster) | keeps `.git/objects` owned by that user |
| commit + push, day to day | **root**, via `deploy-commit.sh` | it commits *as websvcmaster* and pushes *as root* itself — the only command you normally type |
| `git push` by hand | **root** | push needs `sudo -u git git-receive-pack`; websvcmaster has **no sudo** and never will |
| register repo in Redmine | Redmine admin UI | |
websvcmaster's password is **locked** on purpose (`passwd -l`, set by
`01-bootstrap-root.sh`). Enter it only via `su - websvcmaster` from root — never
set a password for it. If a command run as websvcmaster asks for a password, it
is a root command run in the wrong shell: `exit` to root and run it there.
(`passwd -S websvcmaster` must show `L`.)
Repos: `mds-dark.git` (WordPress theme, project "MDS / MIMMAR Web Page Design"),
`dmz-web-deploy.git` (this host's `~/deploy`, project "dmz-web Infrastructure").
### 3.1.1 How Redmine reads them
```ini
# site-redmine.container
Volume=/srv/git:/srv/git:ro
Environment=GIT_CONFIG_COUNT=1
Environment=GIT_CONFIG_KEY_0=safe.directory
Environment=GIT_CONFIG_VALUE_0=*
```
Rootless UID mapping: container uid *n* → host uid **200000 + n − 1**; Redmine
runs as uid 999 → host **200998** (`podman top site-redmine user huser`).
One-time host prep (root):
```bash
semanage fcontext -a -t container_file_t '/srv/git(/.*)?'
restorecon -Rv /srv/git
```
### 3.1.2 New bare repo — root
```bash
R=/srv/git/<repo>.git
sudo -u git git init --bare $R
sudo -u git git -C $R symbolic-ref HEAD refs/heads/main # bare HEAD defaults to master; every repo here uses main
setfacl -R -m u:200998:rX $R # Redmine read access
setfacl -R -d -m u:200998:rX $R # ...also for files future pushes create
restorecon -Rv $R # "not reset as customized by admin" on every file = already container_file_t = OK
git config --global --add safe.directory /home/<user>/<workdir> # lets root push from that working copy
```
### 3.1.3 Working copy, first time — owner user (`su - <user>` from root)
```bash
git config --global user.name "<user>" # once per user, or commit refuses
git config --global user.email "sysadmin@mdsdefense.com" # matching a Redmine user's email links commits to them
cd <workdir>
git init -b main
# .gitignore first: no *.env, *secret*, *password*, *.key/*.pem/*.crt, dumps, archives, data/, tmp/
git add -A && git status --short
grep -nEi 'password|secret|token|key_base' -r . --exclude-dir=.git | grep -viE 'Secret=|podman secret|\$\{?[A-Z_]*(PASSWORD|SECRET)' # must be comments/prompts only
git commit -m "initial import $(date +%F)"
git remote add origin /srv/git/<repo>.git
git log --oneline
exit # back to root
```
### 3.1.4 Push — root
First push of a new working copy (once):
```bash
cd /home/<user>/<workdir>
git push --receive-pack='sudo -u git git-receive-pack' -u origin main
chown -R <user>:<user> .git # root's push leaves root-owned files in .git
```
Expected: `* [new branch] main -> main`. Verify: `sudo -u git git -C /srv/git/<repo>.git log --oneline`.
After that, never push by hand — use `deploy-commit.sh` (E).
### 3.1.5 Redmine
Project → Settings → Repositories → New repository: SCM **Git**, Main repository
✓, Identifier `<repo>`, Path `/srv/git/<repo>.git`, Report last commit ✓ → Create.
Open the Repository tab; the commit must be listed. If not:
`podman exec site-redmine git -C /srv/git/<repo>.git log --oneline` —
"dubious ownership" → safe.directory env missing; "permission denied" → ACL (step 3.1.2).
### 3.1.6 Day-to-day — `deploy-commit.sh` (root)
One root command does the whole cycle in the right identities: `git add -A`
and `git commit` **as websvcmaster** (identity auto-set), a guard that refuses
to commit staged lines that look like literal credentials, `git push`
**as root** via `sudo -u git git-receive-pack`, optional annotated tag, and
`chown` of `.git` back to websvcmaster. Source: `root-bin/deploy-commit.sh` in
the repo; installed as `/usr/local/sbin/deploy-commit.sh` (0750).
```bash
deploy-commit.sh -n # dry run: shows what is staged, commits nothing
deploy-commit.sh -m "what changed" # commit + push
deploy-commit.sh -m "cheat sheet v1.1" -t cheatsheet-1.1 # ...+ tag
deploy-commit.sh -t cheatsheet-1.1 # nothing to commit: tag HEAD, push the tag
deploy-commit.sh -y -m "..." # skip the credential guard after checking the flagged lines
deploy-commit.sh -h
```
Editing still happens as websvcmaster (`su - websvcmaster`, edit, `exit`);
`deploy-commit.sh` never edits files, only `.git`. The guard flags staged lines of
the form `<…password|secret|token|api_key|app_key…> = <literal of 8+ chars>`;
variables (`$X`), placeholders (`<…>`, `...`), Quadlet `Secret=` lines and
comments are ignored. If it fires: move the value to a Podman secret or
`.gitignore` the file and re-run; if the lines are harmless, re-run with `-y`. Install/update the script:
```bash
install -o root -g root -m 0750 /home/websvcmaster/deploy/root-bin/deploy-commit.sh /usr/local/sbin/deploy-commit.sh
```
### 3.1.7 Publishing finished work — `deploy-publish.sh` (root)
Replaces the manual "copy from `/root` into the repo, fix owner, commit, tag, type the wiki into
Redmine" cycle. A delivery is **one file**, `dmz-web-release-<version>.zip` (`<version>` = the cheat sheet
version of that release), dropped into `/root` (with the `pf-app-<x.y.z>.tar.gz` it names, if it carries an
application version); run `deploy-publish.sh` as root. Since 1.6 it **shows the whole plan first and asks one
question**; nothing changes before the answer. It calls `deploy-commit.sh` for the git part, so E still applies.
The package holds the changed files (scripts, the cheat sheet), a `wiki/` folder (pages + png),
`RELEASE` (version, build date, optionally `amends: <note> ...`) and `SHA256SUMS`, and optionally a `releases/` folder with the notes of that release (what changed, steps, what to look at, rollback) and `pf-app.sha256` (the sha256 of the application tarballs, which travel as separate files). Packages are built with `tools/build-release.sh`, which refuses a file older than the published one (the stale `pf-install.sh` of release 1.21 would have stopped there). What the script does:
0. **Package:** unpacked into a fresh private directory; paths are checked (no `..`, absolute paths
or symlinks), the file name must match `RELEASE`, `SHA256SUMS` must verify, and a file that is not
listed in `SHA256SUMS` rejects the package. Then the **sha256 of the package itself is printed**; with `-s <sha256>` (the value from the delivery note) the run stops on a mismatch. If the package carries a **newer `deploy-publish.sh`** than the running one, the plan is made by the package's copy (verified by `SHA256SUMS`) and it is installed together with everything else after the answer (1.5 still installed the new copy first; from 1.6 on nothing changes before the question).
1. **Repo:** each known file is compared by its **version header** with the repo / installed copy:
newer → installed (repo files owned by websvcmaster, `/usr/local/sbin` copies root 0750);
identical → nothing to do; **older, same version with different content, or no version header →
refused** (stops a stale copy overwriting a newer one; `-f` overrides). Known files: cheat sheet,
`snipeit-install.sh`, `add-wordpress-site.sh`, `redmine-install.sh`, `check-sites.sh`,
`verify-host-deps.sh`, `deploy-commit.sh`, `deploy-publish.sh`, `as-web`, `pf-upgrade.sh`, `pf-install.sh`, `pf-mgmt-cheatsheet.md`,
`tools/build-release.sh` — add a line to the `ITEMS` table in the script for another one. `releases/*.md` of the package are copied to `releases/` in the repo: a new note is installed, an identical one is skipped, a note that exists with other content is **refused** (release notes are history; `-f` overrides) unless `RELEASE` names it on its `amends:` line (a later release correcting an earlier note on purpose).
**Then the rest of the plan:** the lines added to `releases/CHECKSUMS.txt` (the package's sha256 and the lines of `pf-app.sha256`), the PF application (the newest version `pf-app.sha256` names, if it is newer than the unit and its tarball is in `/root` with that sha256: the **dry run of `pf-upgrade.sh`** is printed), the wiki pages (read-only check: *would create / update / unchanged*) and older release zips that go to `deploy-done` with this one. Then **one question**: *apply this plan?* (`-n` stops before it; `-Y -s <sha256>` applies without asking).
2. **Commit:** the planned lines are appended to `releases/CHECKSUMS.txt` (a zip cannot hold its own hash; `pf-upgrade.sh` reads the tarball's sha256 from there); `deploy-commit.sh -m "release <version>: <files and versions>"`; a cheat sheet install also
gets the tag `cheatsheet-<version>` (skipped if that tag exists).
3. **Wiki:** `wiki/*.md` → Redmine REST API: page created or updated (parent `Wiki`, the duplicate
`# title` first line dropped, `.png` attached once, unchanged pages skipped). `@@COMMIT@@` in a page
(the Releases table) becomes the commit made in step 2 (on a re-run: the commit of the tag `cheatsheet-<version>`; a page that needs a hash and has none is skipped, never overwritten with the placeholder); `commit:@@TAG:<tag>@@` becomes the commit of that tag (the row of the release before, so no hash is typed by hand).
4. **Tidy:** after a complete, clean run the package is **moved** (never deleted) to
`/root/deploy-done/<timestamp>/`, together with older `dmz-web-release-*.zip` still in `/root`. With refusals, errors, `-n`, `-R` or `-W` it stays in `/root`; running it
again is safe, handled files then show as *identical* and are skipped.
5. **PF:** after a clean publish, `pf-upgrade.sh -y -s <sha256> <version>` upgrades the application (§5.7) — the run the plan showed. `-P` leaves it out (run `pf-upgrade.sh <version>` later; it finds the sha256 in `releases/CHECKSUMS.txt`).
Loose files (no package) still work: put them into `/root` (and `dmz-web-wiki-pages.zip` for the wiki)
and the handled ones are moved to `/root/deploy-done/<timestamp>/`.
```bash
deploy-publish.sh -n -s <sha256> # dry run: the plan, wiki read-only GETs, nothing changed or moved, no question
deploy-publish.sh -s <sha256> # the plan, then "apply this plan?" -- the normal run (newest /root/dmz-web-release-*.zip)
deploy-publish.sh -Y -s <sha256> # the plan and apply it without asking (unattended)
deploy-publish.sh -P # do not upgrade the PF application at the end
deploy-publish.sh -R # wiki only deploy-publish.sh -W # repo only
deploy-publish.sh -m "msg" # own commit message deploy-publish.sh -y # skip deploy-commit's guard
deploy-publish.sh -f # install even when older / equal / no version header
deploy-publish.sh --status # read-only overview: published / installed / waiting (see below)
```
**What is published, installed and waiting?** `deploy-publish.sh --status` answers it and changes nothing: the version of every file in the repo and in `/usr/local/sbin` (a difference is flagged), HEAD and the last `cheatsheet-*` tag, uncommitted or unpushed commits, release packages and `pf-app-*.tar.gz` waiting in `/root` (flagged *NOT PUBLISHED YET* when newer than the last tag), and for PF the `Image=` tag in the repo unit, in the installed unit and of the running `site-pf` container. Lines starting with `!!` are the things to look at.
One-time setup for the wiki step: `deploy-publish.sh --init` writes `/root/.deploy-publish.conf`
(mode 0600; set `RM_PROJECT` to the project **identifier**, Project settings → Identifier); put the
Redmine API key (My account → API access key) into `/root/.redmine-api-key`, `chmod 600`; Redmine
Administration → Settings → API → *Enable REST web service*. Requests go to NPM on this host
(`--resolve track.mdsdefense.com:444:127.0.0.1`), like `check-sites.sh`. The page text in Redmine is
overwritten by the package's text — the first real run replaces pages that were typed in by hand, so
start with `-n`. Bootstrap the first time (the script cannot install itself before it exists):
```bash
install -o root -g root -m 0750 /root/deploy-publish.sh /usr/local/sbin/deploy-publish.sh
deploy-publish.sh --init && deploy-publish.sh -n
```
Afterwards the script updates itself from the package (the running copy is replaced safely).
**Building a package** (wherever releases are put together; root is not needed): the files go into one directory (scripts and cheat sheets at the top, `wiki/`, `releases/`, `pf-app.sha256`, and `AMENDS` listing earlier notes this release corrects), then
```bash
tools/build-release.sh -v 1.24 1.23 -b dmz-web-release-1.23.zip -b dmz-web-release-1.22.zip -b dmz-web-release-1.21.zip -b ~/deploy -a pf-app-1.1.14.tar.gz pf-app-1.1.13.tar.gz <tree>
```
compares every file with the **highest version found in the baselines** (published zips, the repo working copy) and stops on an older copy, a changed file with an unchanged version, a missing version header, a changed note not named in `AMENDS`, a cheat sheet version other than `-v`, or a shell script that fails `bash -n`; with `-a <pf-app tarball>` it also runs the app's label check (`app/i18n.py check`: every key the page uses is in `strings.csv`, placeholders agree in every language) and checks that the tarball's sha256 is in `pf-app.sha256`; it never overwrites an existing zip (a package is never re-issued under the same name).
### 3.1.8 Recovering from the usual mistakes
* `fatal: could not open '.git/COMMIT_EDITMSG': Permission denied` (or any
permission error on commit) → root touched `.git` (committed there, or pushed/tagged
without `deploy-commit.sh`). Fix: `chown -R <user>:<user> /home/<user>/<workdir>/.git`,
then use `deploy-commit.sh` from now on (it chowns every time). Also check root's `~/.gitconfig` didn't pick up the user's identity.
* `Everything up-to-date` on push right after you expected a new commit → the
commit didn't happen (identity error or permission error scrolled past); `git log --oneline`
and `git status --short` in the working copy. A tag made at that moment points at the
old commit: `deploy-commit.sh -t <tag>` after the real commit (it force-moves the tag).
* `error: src refspec main does not match any` → no commit yet on `main` (step 3.1.3 not done).
* `error: key does not contain a section: receivepack` → wrong syntax; use
`--receive-pack=` (step 3.1.4), not `-c receivepack=`.
* `sudo: a password is required` / password prompt → you are websvcmaster; this is a root step (`exit`, then `deploy-commit.sh`).
* Redmine shows the repo empty → bare HEAD still points to `master` (step 3.1.2 `symbolic-ref`).
* `deploy-publish.sh`: `REFUSED: no version header` → the copy is an old/unversioned one; fetch the current file or `-f` if you are sure. `checksum mismatch` / `does not match RELEASE` → the package is damaged or was renamed; get it again. `HTTP 401/403` on the wiki step → API key wrong, REST not enabled, or the account may not edit this project's wiki. `HTTP 404` for every page → wrong `RM_PROJECT` (it must be the identifier, not the project name).
---
_Source: `dmz-web-podman-cheatsheet.md` v1.5 in the `dmz-web-deploy` repo ([[Releases]]). Edit the wiki and the repo copy together._