CI · XB Field Notes

CI artifacts need an explicit handoff contract

Fri, 03 Sep 2027 00:00:00 +0000

A CI job can finish successfully while the next job receives the wrong files. An artifact is a stored output handed to another step, job, person, or release process. Its name alone rarely identifies everything the consumer needs to know. Treat the handoff as a contract covering the producing run, source revision, payload, integrity evidence, access policy, and availability window. Those details turn “download the build” into a checkable operation.

An explicit handoff checks the expected producer, agreed files and payload integrity, then plans retention and access. The retained passed fixture covers a local archive; it does not verify hosted expiry or provenance. No example was rerun for this drawing.

Distinguish transfer from retention

An artifact can contain a binary, test report, coverage data, or a package that later becomes a release input. It is not inherently excluded from the release path. A dependency cache serves a different purpose: speeding up work that can be recreated. Decide what must remain available for approval, diagnosis, or rollback before selecting storage and retention. Rebuilding an expired output may create different bytes and requires its own validation.

GitHub Actions allows custom artifact retention subject to repository, organization, or enterprise limits. Plan around the actual configured window, including weekends and delayed approvals. A requested retention value cannot override the platform’s upper limit. If an artifact must outlive that window, use the project’s durable release or object storage with an explicit lifecycle. Do not describe a short-lived job store as an indefinite release archive.

When it breaks

Downloading a convenient “latest successful” run can pick a different commit, branch, or workflow. Resolve the intended producer explicitly and check the relationship between its source and the release being approved. The consumer also needs a dependency on successful production of the required files. An empty upload or missing artifact must not silently trigger deployment of whatever happens to be present in a workspace.

Integrity and provenance answer different questions. A checksum can detect a changed payload, but an attacker able to replace both the file and its checksum can create a consistent pair. An attestation needs verification of its subject, signer or workflow identity, and the relevant policy. Merely finding an attestation beside a binary is not evidence that the consumer validated it.

Access depends on the platform, repository visibility, and granted permissions; it is not universally equivalent to seeing a workflow. Still, package only the files needed for the handoff. Credentials, environment dumps, private headers, and unfiltered logs can become lasting copies when uploaded. Review both the member list and content before storing an artifact, particularly when build input comes from an untrusted contribution.

Check it quickly

Save the script as artifacts.py and run python3 artifacts.py. It uses only the Python standard library. The producer creates a temporary ZIP containing app.txt and a manifest with a local run identifier, a synthetic source digest, and the payload digest. The consumer reads only those named members and compares the expected producer before returning the payload.

from hashlib import sha256
from pathlib import Path
from tempfile import TemporaryDirectory
from zipfile import ZipFile
import json

payload = b'local build output\n'
source_digest = sha256(b'example source revision\n').hexdigest()
manifest = {'producer_run': 'local-run-41', 'source_sha256': source_digest,
 'files': {'app.txt': sha256(payload).hexdigest()}}


def produce(path, data):
 with ZipFile(path, 'w') as archive:
 archive.writestr('manifest.json', json.dumps(manifest, sort_keys=True))
 archive.writestr('app.txt', data)


def consume(path, expected_run):
 with ZipFile(path) as archive:
 if sorted(archive.namelist()) != ['app.txt', 'manifest.json']:
 raise ValueError('unexpected member set')
 received = json.loads(archive.read('manifest.json'))
 if (received['producer_run'] != expected_run
 or received['source_sha256'] != source_digest):
 raise ValueError('producer identity mismatch')
 data = archive.read('app.txt')
 if sha256(data).hexdigest() != received['files']['app.txt']:
 raise ValueError('payload digest mismatch')
 return data


with TemporaryDirectory() as directory:
 archive = Path(directory) / 'handoff.zip'
 produce(archive, payload)
 assert consume(archive, 'local-run-41') == payload
 rejected = []
 try:
 consume(archive, 'local-run-42')
 except ValueError as error:
 rejected.append(str(error))
 produce(archive, payload + b'changed\n')
 try:
 consume(archive, 'local-run-41')
 except ValueError as error:
 rejected.append(str(error))
 archive.unlink()
 try:
 consume(archive, 'local-run-41')
 except FileNotFoundError:
 rejected.append('artifact missing')
 assert rejected == ['producer identity mismatch', 'payload digest mismatch', 'artifact missing']
 print(json.dumps({'valid_payload_bytes': len(payload), 'rejected': rejected,
 'platform_retention_tested': False}))

The valid handoff returns nineteen bytes. Requesting local-run-42 from the archive produced by local-run-41 raises an identity mismatch. Replacing the payload while keeping its old manifest raises a digest mismatch. Deleting the archive produces a missing-artifact failure. The final result lists all three rejected cases; no failure substitutes a different build.

This is a real local archive exercise, not an execution of GitHub’s retention service or a provenance attestation. The source digest is an illustrative identifier, not a verified Git commit. A modified manifest can still tell a consistent lie. The example proves the stated checks and their limits, including that local deletion models absence without proving a platform expiration schedule.

Make the consumer’s gate explicit

Review the actual download action’s failure behavior. GitHub’s documented digest mismatch behavior includes a warning; do not assume that every integrity warning automatically fails a deployment job. If release policy requires rejection, enforce that gate and retain its result alongside the producer identity. Record where durable release bytes are stored, who can retrieve them, and when transient handoff copies may safely expire.

Sources

GitHub: store and share workflow data, artifact transfer, retention limits, and digest validation, checked 2026-09-13.
GitHub: artifact attestations, provenance evidence and its verification boundary, checked 2026-09-13.

GitHub Actions workflows gate the build

Thu, 02 Sep 2027 00:00:00 +0000

A workflow can produce evidence for a merge decision, but YAML alone does not make that evidence mandatory. A dependable build gate connects the intended event, the exact revision being tested, meaningful test results, and a repository rule requiring the correct check. Review those connections together. A green badge on some earlier run is not proof that the proposed merge has satisfied today’s requirements.

The aggregate decision is only one part of a merge gate: repository rules must require the correct check for the intended event and revision. The retained passed fixture covers the local success predicate only. No example was rerun for this drawing.

Separate execution from enforcement

Files under .github/workflows/ describe triggers and jobs. The on key chooses events; branch protection or rulesets separately decide which checks must pass before merging. Record the stable check name and review the rule whenever it changes. Distinct workflows should avoid ambiguous job names, and the expected check source should match the trusted application.

Check the revision shown in the pull request’s checks box. A pull_request run commonly tests a synthetic merge commit, not simply the contributor’s head commit. Merge queues need the separate merge_group trigger for their candidate combinations. A successful local build or manually dispatched workflow cannot automatically substitute for the required event and revision.

Make the dependency result explicit

Jobs without dependencies can run in parallel, while steps within a job normally run sequentially. needs establishes prerequisites; conditions determine whether work executes after failure or skipping. A workflow containing only one required test job does not need an artificial dependency or event condition. Requiring those keys everywhere is not a useful correctness test.

For an aggregate gate, wait for every mandatory job and inspect its result explicitly. Use if: ${{ always() }} so a failed prerequisite does not simply skip the gate, then require actual success. If optional work may be skipped, encode that exception deliberately. Do not let a generic success message, or continue-on-error on mandatory tests, turn missing evidence into a passing gate.

The needs context contains direct dependencies, not every job earlier in the dependency graph. If the gate must inspect both a build and a test that depends on that build, declare both jobs directly in the gate’s needs. Otherwise the build’s result is not exposed there merely because it is a transitive prerequisite.

Permissions describe the token, not all credentials

permissions controls GITHUB_TOKEN; it does not constrain an unrelated secret credential passed to a command. A restrictive workflow-level declaration can be inherited by jobs, so repeating it in every job is unnecessary. Grant additional access only where required. The offline exercise below uses no token because it neither checks out private source nor calls GitHub APIs.

Ordinary fork pull requests normally receive a read-only token and no repository secrets, subject to repository settings. Secrets are not themselves read-only tokens. Never move untrusted pull-request code into a privileged pull_request_target execution just to obtain secrets. Log masking is a defensive aid, not permission to print credentials or a guarantee that transformed values cannot leak.

When it breaks

A workflow omitted by path or branch filters can leave its required check pending. A conditionally skipped job, however, can satisfy a required-check rule without running tests. These are different outcomes. Rename checks carefully, and verify the failing, skipped, and cancelled paths as well as the successful case on the hosting service.

Caches require compatible keys and verified dependency installation. Ordinary pull-request caches belong to their merge reference; matching keys alone do not make them restorable by the base branch. Avoid unsupported blanket claims that every fork cache can poison main. Also separate test cancellation from deployment recovery: cancelling an in-progress job does not undo external changes it already made.

Check it quickly

The exercise isolates one aggregate gate decision: accept a prerequisite only when its result is exactly success. In a real workflow, the result would come from needs.test.result, with the prerequisite declared in needs. Here the inputs are deliberately synthetic. It is a local decision exercise, not a workflow validator or a replacement for the project’s real tests.

Save this standard-library probe as gate_check.py and run python3 gate_check.py with Python 3 and Bash available. It runs the shell predicate with synthetic results and includes a deliberately failing test assertion. It writes no files and contacts no service.

import os
import subprocess
import sys

subprocess.run([sys.executable, "-c", "assert 2 + 2 == 4"], check=True)
negative = subprocess.run([sys.executable, "-c", "assert 2 + 2 == 5"],
 capture_output=True, text=True)
assert negative.returncode != 0 and "AssertionError" in negative.stderr
print("test-negative-control: rejected")
command = 'test "$TEST_RESULT" = success'
for result in ("success", "failure", "cancelled", "skipped", "", "unexpected"):
 run = subprocess.run(["bash", "--noprofile", "--norc", "-c", command],
 env={"PATH": os.environ["PATH"], "TEST_RESULT": result},
 capture_output=True, text=True)
 accepted = run.returncode == 0
 assert accepted == (result == "success"), (result, run)
 print(f"{result or '<missing>'}: {'accept' if accepted else 'reject'}")
print("PASS: local predicate only; GitHub enforcement not exercised")

Expect the negative control to be rejected, only success to be accepted, and the final scope reminder. This verifies the local command and its rejection cases. It does not parse arbitrary YAML, evaluate GitHub expressions, schedule jobs, inspect repository rules, or prove merge blocking. Those remain hosted integration checks against the actual repository configuration.

Sources

GitHub: workflow syntax, dependencies, conditions and token-permission inheritance, checked 2026-10-15.
GitHub: understanding Actions, workflows, events, jobs and steps, checked 2026-10-15.
GitHub: troubleshooting required status checks, revision identity, skipped checks and merge queues, checked 2026-10-15.
GitHub: workflow events, fork pull requests and privileged trigger boundaries, checked 2026-10-15.
GitHub: dependency caching, branch and pull-request cache scopes, checked 2026-10-15.
GitHub: using secrets, secret availability and log handling, checked 2026-10-15.
GitHub: needs context, direct dependencies and job-result values, checked 2026-10-18.

Copy dependency inputs before application code

Tue, 17 Aug 2027 00:00:00 +0000

Dockerfile order determines which earlier inputs an expensive build operation depends on. If application source is copied before dependency installation, changing that source can make the installation run again even when the dependency declaration is unchanged. Copying the dependency inputs first, installing them, and copying application code afterward creates a smaller dependency boundary that matches the work the installer actually needs.

Source-supported explanation of the article’s historical example. Current audit remains revised, execution blocked. No Docker commands were executed in this visual work; no new runtime, page, integration or publication credit.

When it breaks

A broad COPY . . before package installation makes documentation, generated output, or unrelated source edits potential reasons to repeat expensive work. The problem is not that COPY is inherently slow. It is that the later operation depends on filesystem state containing changes that were unnecessary for resolving and installing the selected dependencies.

Copying only a manifest is insufficient when the install also consumes a lockfile, local package source, patches, workspace metadata, or a package-manager configuration file. Omitting a real dependency can preserve a cached result that no longer matches the intended build. The correct boundary includes every actual installer input, not simply whichever single filename appears in a common Dockerfile example.

Cache ordering also does not fix mutable dependencies. An unchanged install command may retain an old result while a clean build resolves different remote content. Pinning versions and verifying hashes addresses artifact selection; controlling COPY order addresses reuse. Both concerns matter, and making a build faster does not establish that its package graph is reproducible or current.

Check it quickly

Run this host Python script with a Docker builder and the pinned base available. It downloads two public idna wheels over HTTPS and verifies their fixed SHA-256 values before any build. Build RUN instructions use no external network, and pip installs with required hashes from the local wheel directory; image resolution may still contact a registry. The recorded environment used Docker 29.3.1 and Python 3.11.16 inside the Linux arm64 base:

from pathlib import Path
from tempfile import TemporaryDirectory
from urllib.request import urlopen
import hashlib,json,subprocess,uuid

BASE='python@sha256:528257d48c1da0dcecc2e725d1ae34498d60c965f1241e39cd6a85a8859bdf84'
WHEELS={
 '3.10':('https://files.pythonhosted.org/packages/76/c6/c88e154df9c4e1a2a66ccf0005a88dfb2650c1dffb6f5ce603dfbd452ce3/idna-3.10-py3-none-any.whl','946d195a0d259cbba61165e88e65941f16e9b36ea6ddb97f00452bae8b1287d3'),
 '3.11':('https://files.pythonhosted.org/packages/0e/61/66938bbb5fc52dbdf84594873d5b51fb1f7c7794e9c0f5bd885f30bc507b/idna-3.11-py3-none-any.whl','771a87f49d9defaf64091e6e6fe9c18d4833f140bd19464795bc32d966ca37ea')}
def docker(*args,check=True):
 result=subprocess.run(['docker',*args],capture_output=True,text=True,timeout=120)
 if check:assert result.returncode==0,result.stderr
 return result

name='xbcatm-order-'+uuid.uuid4().hex[:10];tags=[name+':early',name+':late']
try:
 with TemporaryDirectory(prefix=name+'-') as directory:
 root=Path(directory);(root/'wheels').mkdir()
 for version,(url,digest) in WHEELS.items():
 with urlopen(url,timeout=40) as response:data=response.read()
 assert hashlib.sha256(data).hexdigest()==digest
 (root/'wheels'/url.rsplit('/',1)[1]).write_bytes(data)
 install='RUN pip install --no-index --no-deps --require-hashes --find-links=/wheels -r /app/requirements.txt && python -c "import time;open(\'/installed\',\'w\').write(str(time.time_ns()))"\n'
 common=f'FROM {BASE}\nLABEL example.run="{name}"\nCOPY wheels /wheels\n'
 (root/'early.Dockerfile').write_text(common+'COPY requirements.txt app.py /app/\n'+install+'CMD ["python", "/app/app.py"]\n')
 (root/'late.Dockerfile').write_text(common+'COPY requirements.txt /app/\n'+install+'COPY app.py /app/\nCMD ["python", "/app/app.py"]\n')
 def requirement(version):
 (root/'requirements.txt').write_text(f'idna=={version} --hash=sha256:{WHEELS[version][1]}\n')
 def application(message):
 (root/'app.py').write_text(f'import idna\nprint({message!r},idna.__version__,idna.encode("bücher.example").decode())\n')
 def build():
 for tag,kind in zip(tags,['early','late']):docker('build','--network','none','-f',str(root/(kind+'.Dockerfile')),'-t',tag,str(root))
 def marks():
 return [docker('run','--rm','--network','none',tag,'cat','/installed').stdout for tag in tags]
 requirement('3.10');application('first');build();first=marks()
 application('second');build();second=marks()
 assert first[0]!=second[0] and first[1]==second[1]
 for tag in tags:assert docker('run','--rm','--network','none',tag).stdout.strip()=='second 3.10 xn--bcher-kva.example'
 print('editing only application code reruns the early-copy dependency install but reuses the late-copy install')
 requirement('3.11');build();third=marks()
 assert all(a!=b for a,b in zip(second,third))
 for tag in tags:assert docker('run','--rm','--network','none',tag).stdout.strip()=='second 3.11 xn--bcher-kva.example'
 print('changing the hashed requirement reruns both installs and actually changes idna from 3.10 to 3.11')
finally:docker('image','rm',*tags,check=False)

The early-copy Dockerfile copies both requirements.txt and app.py before pip runs. The late-copy version copies the requirement first, runs the same installation command, and copies the application afterward. Both include the verified wheel directory before installation because those wheel files are genuine inputs. A marker written immediately after pip records whether that installation operation executed.

The initial application uses idna 3.10 to encode bücher.example. Both images run the actual installed library and produce the expected ASCII domain xn--bcher-kva.example. This exercises a real third-party dependency, rather than replacing dependency installation with a sleep or treating a successful image build as proof that the application can import its package.

After only the application message changes from first to second, both images print the new message with version 3.10. The early-copy image gets a different installation marker, while the late-copy image keeps its original marker. The output proves the code update reached both images; the marker comparison identifies which dependency work was unnecessarily repeated.

Next, the requirement changes to idna 3.11 with its matching hash. Both installation markers change, and both applications report version 3.11 with the same expected domain conversion. This is the necessary opposite case: a genuine dependency declaration change must invalidate the install in both layouts. A layout that ignored this input would be fast but incorrect.

The experiment supplies both wheels from the beginning so changing the requirement does not simultaneously alter the wheel directory. That keeps the cause of the second invalidation explicit. Temporary images and files are cleaned up without pruning unrelated builder state. Installation timestamps are test instrumentation, not a recommended input for reproducible production artifacts.

Match the cache boundary to the package boundary

Review what the installer reads, then group those inputs before the install operation. Keep unrelated files outside that COPY scope and use .dockerignore to exclude material the build never needs. An ignored file cannot later satisfy a required COPY, so check actual build-context contents when a supposedly present dependency disappears.

Package-manager cache mounts can reduce downloads when an install genuinely must rerun, but they do not eliminate the need for correct invalidation or verified outputs. Dependency installation and download-cache reuse are different layers of optimization. Test the resulting application after changes to either one.

Measure improvement on representative builds: unchanged inputs, source-only edits, and dependency upgrades. Retain correctness assertions for all three cases. A useful Dockerfile makes the necessary work repeat and the unnecessary work reusable, with enough evidence to tell those cases apart.

Sources

Optimize Docker cache usage, stable dependency layers and narrow COPY operations, checked 2026-09-12.
Docker cache invalidation, how changed inputs invalidate dependent work, checked 2026-09-12.
pip install reference, offline wheel installation and required hashes, checked 2026-09-12.
Docker build network mode, RUN networking scope and the separate image-resolution boundary, checked 2026-10-19.

CI · XB Field Notes

CI artifacts need an explicit handoff contract

Distinguish transfer from retention

When it breaks

Check it quickly

Make the consumer’s gate explicit

Sources

GitHub Actions workflows gate the build

Separate execution from enforcement

Make the dependency result explicit

Permissions describe the token, not all credentials

When it breaks

Check it quickly

Further reading

Sources

Copy dependency inputs before application code

When it breaks

Check it quickly

Match the cache boundary to the package boundary

Sources