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.

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

CI that shows on every pull request keeps reviews honest. The workflow YAML in the repo is that contract, versioned with the code it checks.

YAML is the contract

The workflow YAML says both when something runs and with what rights, so it is the whole contract rather than just a recipe. A on: block names the triggers, a permissions: block pins what the workflow can touch, and a jobs: section declares the runners and steps. Because on is read before any job runs, a workflow is also where you decide that a pull_request must pass tests to be mergeable or a schedule can run it unsupervised. Version the file with the code it checks, so a branch’s CI always reflects the branch’s own contract.

Jobs and steps run in order

Jobs default to running in parallel, while steps inside a job run sequentially, so the graph you get is the combination of those two rules. A failing step makes the rest of its job conditional; whether later jobs still run is controlled by needs/if, and by the job-level concurrency and matrix settings. This ordering is what turns a workflow into a gate that blocks a merge on red, yet it is fully readable from the file. The practical habit is to keep the fast checks early and the expensive ones downstream, so the gate fails cheap before it fails slowly.

Secrets stay close to the runner

Secrets are injected on the runner, scoped to the workflow, and never printed, but a workflow with broad permissions can still read the repository, so the smallest effective grant is the safety mile. Give each job the permissions it needs instead of the default wider set, and scope environments so secrets reach only the jobs that truly run there. Validate the effective permissions the way you would a production role: a workflow is code that runs with your credentials on every trigger, so a malicious or outdated entry is a long-term credential you are checking in. Rotate anything that must live outside the branch.

When it breaks

A green workflow means nothing if branch protection does not require it. The classic failure is renaming the gate job from test to verify while the rule still waits for the old name: requests block forever on a check that never reports, or an administrator allows bypass and the gate becomes decoration. Fork requests add a second variant: secrets stay read-only, a job needing a deploy token is skipped, and a queue that treats skipped as passed ships untested code. Audit the required list after every rename.

The other failures look like flakes until you read the file. A cache keyed only on runner.os restores last week’s node_modules after the lockfile changed, so green means stale, and a cache written by a fork request can poison main when keys collide. Secrets leak quietly: set -x, verbose curl, or echo ${{ secrets.TOKEN }} prints the value into logs every reader keeps. Two pushes sharing one concurrency group cancel each other, the deploy job dies halfway, and the retry assumes the first run finished.

Check it quickly

Save the following as gate_check.py in a scratch directory and run python3 gate_check.py. It uses only the standard library and writes no files. The bad sample is a negative control, not a template.

"""Minimal gate check for a GitHub Actions workflow (standard library only)."""
import re

GOOD = """name: gate
on:
 pull_request:
permissions:
 contents: read
jobs:
 test:
 runs-on: ubuntu-latest
 permissions:
 contents: read
 steps:
 - run: npm test
 gate:
 needs: [test]
 if: github.event_name == 'pull_request'
 runs-on: ubuntu-latest
 permissions: {}
 steps:
 - run: echo gate ok
"""

BAD = """name: gate
on: [push]
jobs:
 test:
 runs-on: ubuntu-latest
 steps:
 - run: echo ${{ secrets.DEPLOY_TOKEN }}
 deploy:
 runs-on: ubuntu-latest
 permissions:
 contents: write
 steps:
 - run: echo deploy
"""


def check_workflow(text):
 """Return a list of gate violations found in a workflow string."""
 errors = []
 if not re.search(r"(?m)^permissions\s*:", text):
 errors.append("missing top-level permissions: pin contents: read at the top")
 else:
 top = text.split("jobs:")[0] if "jobs:" in text else text
 if re.search(r"write-all|write", top):
 errors.append("top-level permissions too broad: use contents: read")
 if "jobs:" not in text:
 return errors + ["missing jobs: section"]
 jobs = {}
 current = None
 buf = []
 for line in text.split("jobs:", 1)[1].splitlines():
 head = re.match(r"^ ([A-Za-z0-9_-]+):\s*$", line)
 if head:
 if current:
 jobs[current] = "\n".join(buf)
 current = head.group(1)
 buf = [line]
 elif current is not None:
 buf.append(line)
 if current:
 jobs[current] = "\n".join(buf)
 if not jobs:
 return errors + ["no jobs found under jobs:"]
 if not any(re.search(r"(?m)^\s+needs\s*:", chunk) for chunk in jobs.values()):
 errors.append("missing needs: no job waits for tests, the gate cannot order checks")
 if not any(re.search(r"(?m)^\s+if\s*:", chunk) for chunk in jobs.values()):
 errors.append("missing if: no job guards on the event, costly work runs everywhere")
 for name, chunk in jobs.items():
 if not re.search(r"(?m)^\s+permissions\s*:", chunk):
 errors.append(f"job '{name}' missing permissions: grant each job least privilege")
 elif re.search(r"write-all|contents\s*:\s*write", chunk):
 errors.append(f"job '{name}' permissions too broad: keep contents: read or {{}}")
 for line in text.splitlines():
 if "secrets." in line and re.search(r"\becho\b|set\s+-x|curl\s+.*-v", line):
 errors.append(f"possible secret leak to logs: {line.strip()[:80]}")
 break
 return errors


def check(ok, message):
 if not ok:
 raise AssertionError(message)


def main():
 good = check_workflow(GOOD)
 bad = check_workflow(BAD)
 print(f"good workflow: {len(good)} problems")
 for item in good:
 print(f" unexpected: {item}")
 print(f"bad workflow: {len(bad)} problems")
 for item in bad:
 print(f" found: {item}")
 check(not good, f"good sample must pass, got: {good}")
 check(len(bad) >= 3, f"bad sample must fail visibly, got: {bad}")
 check(any("needs" in item for item in bad), "bad sample must expose missing needs")
 check(any("permissions" in item for item in bad), "bad sample must expose permissions")
 check(any("secret" in item for item in bad), "bad sample must expose secret leak")
 print("PASS: gate waits on tests, guards on the event, and stays least-privilege")


if __name__ == "__main__":
 main()

The bad sample fails the three gate rules at once. A missing top-level permissions block and a job without its own grant fail least privilege, and contents: write fails it explicitly. No job declares needs, so nothing waits for tests, and no job declares if, so costly work runs on every push. Echoing secrets.DEPLOY_TOKEN trips the leak check. The good sample passes because test stays read-only and gate waits on it behind an event guard.

The assertions passed with Python 3.12 on macOS. The fixture matches indentation with regular expressions, not a real YAML parser, so it misses anchors and reusable workflows. It also cannot see branch protection or secret rotation. Before deployment, check a real workflow and confirm the required name in the branch settings.

Sources

GitHub: workflow syntax, the workflow schema, checked 2027-08-15.
GitHub: understanding actions, the event-driven model, checked 2027-08-15.

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.

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. Container builds use no network, and pip installs with required hashes from the local wheel directory. 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.

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

YAML is the contract

Jobs and steps run in order

Secrets stay close to the runner

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