105 lines
6.1 KiB
TeX
105 lines
6.1 KiB
TeX
\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.
|