\chapter{Automated Manual Build}
\ChapterLabel{AutomatedManualBuild}
\index{Gitea Actions}\index{runner}\index{build artifact}
\begin{devopsNote}[Draft: verification incomplete]
This chapter addresses course assignment Chapter 3. Its chapter number in
this living manual may differ. Vincent reported a successful local build
of the original manual in an Ubuntu VM on October 9, 2026. The new automated
build script, runner registration, Gitea execution and artifact upload require
their own verification. No pending check below is claimed to have passed.
\end{devopsNote}

\section{Source and trigger}
Source repository: \url{https://git.137-184-97-250.nip.io/stevens-smartpark/smartpark-app}.
Main source: \texttt{latex-manual/devopsAssignment.tex}.
Workflow: \texttt{.gitea/workflows/manual.yml}. Configured push branches are
\texttt{main}, \texttt{chapter3-build-automation} and \texttt{chapter3-build-test}.
HTTPS Git traffic uses public port 443 at the proxy; the handoff reports
private Gitea port 3000. The external VM uses the public HTTPS hostname,
not the Droplet's private container DNS. The runner needs no public inbound
submission port. \textbf{Pending:} source/workflow commit links, actual push
event and run link, verified network diagram and access path.

\section{Runner setup}
Proposed host: Vincent's Ubuntu 22.04.5 LTS VirtualBox VM, x86\_64,
approximately 4 GB allocated RAM and 25 GB virtual disk. These are
user-reported observations, not a fresh resource measurement.
Proposed repository-scoped runner: Gitea Runner 2.3.0, label
\texttt{smartpark-latex:host}, capacity one, dedicated unprivileged Linux
account. It uses installed tools directly in the VM and does not use Docker.
\textbf{Pending:} final owner/location, installed version, online screenshot,
job assignment, resource measurements, reboot/service test and availability
agreement for grading. Update this section if Nica hosts the runner instead.

\section{Reproducible compilation}
Run \texttt{python3 ci/build\_manual.py} from a checkout. The script copies
the source into a fresh temporary directory, invokes \texttt{latexmk -pdf}
with error stopping and shell escape, generates glossary and index, and
finishes the PDF. BibTeX is coordinated by latexmk. Shell escape permits
minted to invoke Pygments; source and workflow authors must be trusted.
Output: \texttt{build/manual/SmartPark-Manual.pdf}.
Nonzero tool exit status, missing PDF and unresolved reference/citation
summaries fail the build. A previous deliverable is removed before building.
\textbf{Pending:} actual command output, successful clean-build log, package
versions from \texttt{build-info.txt}, and reproduction by another teammate.

\section{PDF version traceability}
The build identification page retains the human-maintained document version
and displays the triggering revision and run number. Local runs display
\texttt{local}; modified local working trees display \texttt{dirty}.
The generated metadata exists only in the temporary build directory.
The workflow never commits or pushes generated metadata.
\textbf{Pending:} screenshot of a real Actions PDF and its matching commit
and run. Local identifiers are not Gitea evidence.

\section{Downloadable artifact}
The workflow requests an artifact named with the run number and commit,
containing the manual PDF and nonsecret build metadata. It requests 30 days
retention. This request is not proof of the server's applied retention policy.
\textbf{Pending:} verified artifact upload compatibility, actual retention,
run/artifact link, download and visual inspection. Artifacts are not backups.

\section{Change, failure, and repair evidence}
\textbf{Pending:} fill the evidence worksheet in
\texttt{docs/ch3-evidence.md}, then summarize the real results here.
Include two successive source changes producing successful PDFs and a
controlled LaTeX syntax error followed by repair on a workflow-covered
test branch. Record date, expected and actual result, full commit, run URL,
visible PDF identifier and artifact link. A failed compile must not publish
a successful PDF. Do not substitute Chapter 4 Jenkins tests for these runs.

\section{Runner and secret boundary}
Only reviewed team workflows should reach this runner. No pull-request
event is configured in this draft. Push-only triggers are not complete
access control: restrict who may push or modify workflows, and review other
workflows that can target the runner label. Host jobs share an account and
environment and can access that account's runner credentials; this is not
isolation between jobs. Use a dedicated VM and unprivileged service account,
no Docker group, no passwordless sudo, no personal Windows shared folders
or SSH keys, and no untrusted jobs. Registration credentials stay outside Git.
\textbf{Pending:} actual edit rights, repository scope, credential storage
controls and nonsecret configuration links.

\section{Manual quality and controls}
This is a draft addition, not a completed assignment submission. The draft
history entry identifies the new chapter; existing Hosts and Passwords
tables have not been changed by the installer and require review before
submission. Add the actual runner host, owner, role, outbound access and
availability; document credential ownership and storage hints only.
\textbf{Pending:} table updates, final version/title/date, glossary terms,
citations, dated figures, run hyperlinks, AI assistance review and removal
of every completed placeholder. Preserve truthful notes about any failures.

Troubleshooting: for a queued job check online status and label; for checkout
failure check DNS, HTTPS and repository permissions; for TeX failure inspect
the first compiler error; for upload failure inspect the artifact step and
server/action compatibility. A successful compiler run alone does not prove
artifact upload. The operator checks the runner service, corrects the cause,
and pushes a source correction to produce a new traceable run.

References: \url{https://docs.gitea.com/runner/2/},
\url{https://docs.gitea.com/runner/2/labels/},
\url{https://docs.gitea.com/usage/actions/artifacts/}.
Replace or supplement these links with the manual's normal bibliography
entries during editorial review.

First automated source-change demonstration.\par

Second automated source-change demonstration.\par