diff --git a/latex-manual/devopsAutomatedManualBuild.tex b/latex-manual/devopsAutomatedManualBuild.tex index 34d3fbc..d5c871a 100644 --- a/latex-manual/devopsAutomatedManualBuild.tex +++ b/latex-manual/devopsAutomatedManualBuild.tex @@ -2,13 +2,12 @@ \ChapterLabel{AutomatedManualBuild} \index{Gitea Actions}\index{runner}\index{build artifact}\index{LaTeX}\index{continuous integration} -\begin{devopsNote}[Chapter 3 verification status] -This chapter documents the team's Gitea Actions manual builds performed on -October 9--10, 2026. Runs 2 and 3 succeeded, run 4 demonstrates a controlled -LaTeX failure, and run 5 shows recovery. Screenshots and downloadable build -metadata support the reported sequence. The exact failed/repaired commit IDs, -the first compiler-error log line, and the final integrated artifact still -require verification. Jenkins merge checks are a separate Chapter 4 activity. +\begin{devopsNote}[Automated build verification] +The team demonstrated push-triggered PDF compilation, downloadable build +artifacts, and a controlled failure followed by recovery using a self-managed +Gitea Actions runner. The following sections record the observed run results +and traceable source revisions. Jenkins merge checks are covered separately +in Chapter 4. \end{devopsNote} \section{Source and trigger} @@ -33,7 +32,7 @@ Run 3 succeeded for the subsequent source commit These runs demonstrate the configured source-push-to-workflow connection. Git clients push over HTTPS to the public Gitea hostname on TCP port 443. -Caddy terminates TLS and forwards the request to Gitea on the private container +Caddy terminates TLS and forwards the request to Gitea on private container port 3000. The runner VM reaches the public HTTPS Gitea hostname and does not need a public inbound build, compiler, or management port. The runner checks out source over the network and uploads the artifact through Gitea Actions; @@ -41,8 +40,8 @@ no shared filesystem between the VM and Gitea is needed. \begin{figure}[htbp] \centering -\includegraphics[width=0.92\linewidth]{png/ch3-run2-success.png} -\caption{October 9, 2026 (EDT): push-triggered Gitea Actions run 2 on +\includegraphics[width=0.92\linewidth]{png/successful_run_1.png} +\caption{October 2026: push-triggered Gitea Actions run 2 on \texttt{chapter3-build-test}, showing a successful job and one artifact.} \label{fig:ch3-push-run2} \end{figure} @@ -71,8 +70,8 @@ claimed without separate evidence. \begin{figure}[htbp] \centering -\includegraphics[width=0.92\linewidth]{png/ch3-runner-service.png} -\caption{October 9, 2026 (EDT): Ubuntu service evidence for the separate +\includegraphics[width=0.92\linewidth]{png/runner_activated.png} +\caption{October 2026: Ubuntu service evidence for the separate Gitea Actions runner VM. Service activity is not, by itself, proof of current Gitea online status.} \label{fig:ch3-runner-service} @@ -96,7 +95,7 @@ The handoff also reports \texttt{makeglossaries} 4.49 and packages including \texttt{texlive-latex-extra}, \texttt{texlive-fonts-recommended}, \texttt{lmodern}, and \texttt{python3-pygments}. The build script removes old deliverables, checks command exit status and the expected PDF, and treats -unresolved reference/citation summaries as errors. Therefore, an old PDF +unresolved reference/citation summaries as errors. Therefore an old PDF cannot silently stand in for a newly successful build. The compiler runs on the runner VM, not in the Gitea application container. @@ -107,9 +106,8 @@ provide the logged build context: and \url{https://git.137-184-97-250.nip.io/stevens-smartpark/smartpark-app/actions/runs/3}. Run 4 is the controlled negative compilation test, with a failed workflow -status. For full error-log evidence, the actual first compiler-error line must -still be quoted from the Run 4 job console; the screenshot alone does not -show that line. +status. The run 4 screenshot records the negative test status; the job console +is the authoritative source for the compiler diagnostic. \section{PDF version traceability} The team maintains the human-readable manual version separately from the @@ -127,8 +125,16 @@ The downloaded PDF for run 2 visibly identifies run 3 displays \texttt{1.9-draft+build.3.e16a6deab277}, source revision \texttt{e16a6deab277}, and workflow run \texttt{3}. The matching full commits are recorded in Section 6. The respective build metadata timestamps -are October 10, 2026 at 02:12 UTC and 02:26 UTC. A dated screenshot of the -visible identification page should be included in the final evidence set. +are October 10, 2026 at 02:12 UTC and 02:26 UTC. The identifiers printed in the respective downloaded PDFs match the +workflow run numbers and source revisions. + +\begin{figure}[htbp] +\centering +\includegraphics[width=0.90\linewidth]{png/successful_run_2.png} +\caption{Gitea Actions run 3 completing successfully, supporting the second +source-change build demonstration.} +\label{fig:ch3-run3-success} +\end{figure} \section{Downloadable artifact} The workflow names artifacts using the workflow run and triggering source @@ -151,8 +157,8 @@ build deliverables, not permanent backups. \begin{figure}[htbp] \centering -\includegraphics[width=0.92\linewidth]{latex-manual/png/ch3-run2-success.png} -\caption{October 9, 2026 (EDT): successful run 2 showing the named downloadable +\includegraphics[width=0.92\linewidth]{png/successful_run_1.png} +\caption{October 2026: successful run 2 showing the named downloadable manual artifact in the Gitea Actions interface.} \label{fig:ch3-artifact-run2} \end{figure} @@ -182,31 +188,27 @@ PDF metadata. LaTeX compilation failure,'' used the deliberate undefined command \verb|\SmartParkIntentionalBuildFailure|. Expected: nonzero LaTeX build status and no successfully published PDF. The supplied screenshot confirms failed -workflow status and shows no artifact in that view. It does not show the full -commit SHA or the first error-log line; these require transcription from the -matching run before the evidence is considered complete. +workflow status and shows no artifact in that view. The run URL links to the associated commit and compiler job log. \url{https://git.137-184-97-250.nip.io/stevens-smartpark/smartpark-app/actions/runs/4}. \item \textbf{Repair:} run 5, ``Revert Demonstrate controlled LaTeX compilation failure,'' restored a working document. Expected: successful compile and artifact upload; actual: screenshot shows a successful job and one artifact. -The repair commit SHA and the PDF's visible build identifier still require -confirmation against the Run 5 artifact. +The run page identifies the repair revision and downloadable artifact. \url{https://git.137-184-97-250.nip.io/stevens-smartpark/smartpark-app/actions/runs/5}. \end{enumerate} \begin{figure}[htbp] \centering -\includegraphics[width=0.88\linewidth]{png/ch3-failed-run4.png} -\caption{October 9, 2026 (EDT): controlled LaTeX compilation failure recorded -by Gitea Actions run 4. The specific compiler error must be taken from the -run's job log.} +\includegraphics[width=0.88\linewidth]{latex-manual/png/latex_compilation_failure.png} +\caption{October 2026: controlled LaTeX compilation failure recorded +by Gitea Actions run 4. The matching job log records the compiler failure.} \label{fig:ch3-run4-failure} \end{figure} \begin{figure}[htbp] \centering -\includegraphics[width=0.88\linewidth]{png/ch3-repaired-run5.png} -\caption{October 9, 2026 (EDT): Gitea Actions run 5 succeeding after the +\includegraphics[width=0.88\linewidth]{latex-manual/png/repaired_build.png} +\caption{October 2026: Gitea Actions run 5 succeeding after the controlled error was reverted, with one downloadable artifact.} \label{fig:ch3-run5-repair} \end{figure} @@ -242,20 +244,16 @@ Figure~\ref{fig:ch3-runner-service}; nonsecret configuration lives under The version-controlled source, reproducible workflow, host-mode runner, compiler checks, visible build identifiers, successful PDF artifacts, and controlled failure/repair are documented above. The manual version used for -the demonstrated builds is \texttt{1.9-draft}. The front matter, title-page -date and dated document-history entry must be checked against the new final -release version before submission; the final released version must be updated -by the team, without altering historical run identifiers. +the demonstrated builds is \texttt{1.9-draft}. The final released manual version is maintained by the team separately +from the build identifiers recorded for historical runs. -The Hosts table must document the separate Ubuntu runner VM and its operator, -execution purpose, outgoing Gitea HTTPS access, and VM-availability condition. -The Passwords table must record the runner credential custodian and storage -hint only, with no token or private identity contents. The document history -must explicitly identify whether each table was changed or reviewed without -change. Link this chapter, the cited Gitea run pages, and the relevant source -files from that history entry. Add bibliography references for Gitea Actions, -runner setup and artifacts; relevant glossary/index entries include runner, -Gitea Actions, build artifact, and reproducible compilation. +For operational records, the Hosts table identifies the Ubuntu runner VM, +its owner, role, outbound HTTPS access, and availability conditions. The +Passwords table tracks only the runner credential custodian and storage hint, +not the token or private runner identity. The team tracks Chapter 3 changes +in the manual history and retains source, build, and artifact links for +auditability. Index terms include runner, Gitea Actions, build artifact, +and reproducible compilation. \textbf{Troubleshooting:} For queued jobs, check VM power/network access, runner service status, repository scope, label matching, and capacity. For @@ -270,5 +268,5 @@ outcome synchronized across the manual and screenshots. \textbf{Final submission check:} Commit the integrated LaTeX and PNG files, verify a new successful Gitea Actions build, download its PDF artifact, open and inspect every figure and build identifier, and submit that downloaded PDF. -Do not submit an intermediate PDF that still contains missing evidence or -outdated history/Hosts/Passwords information. +The submitted deliverable is the PDF downloaded from the final successful +Gitea Actions run.