The Tiny Tapeout workflows
This page answers: what does each of the digital template’s six jobs do, how long does it take, what does it leave behind, and what does it look like when it fails?
Reading a workflow file showed how to read any workflow, using the template’s gds.yaml as the example. This page goes through the digital template’s workflows job by job, so that when one goes red you already know what it was checking. Everything here is from TinyTapeout/ttsky-verilog-template at a42e666 and from Tiny Tapeout’s actions at the tag its workflows name, ttsky26d, which pointed at commit 395eedb when we read it on Nov 15, 2026. The times are from runs in the team’s repositories.
One push, six jobs
A push to your repository starts three workflows. Between them they run six jobs, each on its own fresh runner:
| Workflow | Job | What it checks | Time in the team’s runs | What it uploads |
|---|---|---|---|---|
docs |
docs |
info.yaml and docs/info.md, then builds the datasheet page |
30 s (hart-1) to 53 s (sentry) |
PDF |
test |
test |
Your cocotb test, on your RTL | 20 to 46 s | test-results |
gds |
gds |
Builds the layout with LibreLane | 3 min 50 s (sentry, 2x2) to 28 min (protocol-emulator, 6x2 on IHP’s process) |
GDS_logs, tt_submission, gds_render |
gds |
precheck |
Tiny Tapeout’s checks on the layout | 91 to 315 s | precheck_reports |
gds |
gl_test |
Your cocotb test again, on the gate-level netlist | 35 to 62 s | gatelevel_test_results |
gds |
viewer |
Publishes a page that shows your layout in 3D | 6 to 25 s | github-pages |
The last three jobs each have needs: gds, so they wait for it and are skipped if it fails. The fourth workflow file, fpga.yaml, is switched off: its trigger lists only a branch called none.
docs
The docs job has a single step of its own, “Build docs”, which runs Tiny Tapeout’s docs action. Inside it, the section “Check info.yaml and docs/info.md” does the checking. It runs the same validator the gds job uses on info.yaml, and then a check of docs/info.md that looks for the template’s placeholder sentences. If either finds a problem, the job prints a list under ## Errors in info.yaml or ## Errors in docs/info.md, copies it into the run’s summary page, and stops. Otherwise it installs Pandoc and Typst, builds your datasheet page as a PDF and uploads it as the PDF artifact.
Tiny Tapeout’s own guide says that “projects with a failing docs action will still be included onto the shuttle”, though without their datasheet page. In this course a red docs counts as red, because the errors it finds are usually also errors in the files every other tool reads.
You’ll see its failures in Lab 01, where the template’s empty fields fail it on the first commit, and in breakages 1, 2 and 5 of Lab 02.
test
The test job is the only one written out in your repository rather than in Tiny Tapeout’s actions, so you can read every step in .github/workflows/test.yaml. It installs Icarus Verilog from Ubuntu’s packages (12.0 on the ubuntu-24.04 runner), installs Python 3.11 and the packages in your test/requirements.txt (the template pins cocotb==2.1.0 and pytest==8.4.2), and then runs the “Run tests” step:
- name: Run tests
run: |
cd test
make clean
make
# make will return success even if the tests fail, so check results.xml for failed tests
python -m cocotb_tools.check_results results.xmlAs Reading a workflow file says, the comment was true of cocotb 1.x. With cocotb 2.x, make reads results.xml itself at the end of every simulation, through the same check_results module; you can see the line that does it in cocotb’s Makefile.icarus, in the recipe for results.xml. So with the template’s cocotb 2.1.0 a failing test stops the step at make, and the last line only runs when make has passed.
After “Run tests”, two steps run even when it failed: “Test Summary” turns results.xml into a table on the run’s summary page, and the last step uploads tb.fst and results.xml as the test-results artifact. When the simulation never started, both complain that the files are missing, as Reading a workflow file shows for protocol-emulator. Both complaints are about files that the failed step never wrote, so look further up the log for the cause.
A green test job means your test passed on your RTL with the runner’s tools. It doesn’t mean the test checks much: the template’s test drives one pair of inputs and checks one output, and it stays green on a design that only gets that one case right.
gds
The gds job
“Build GDS” is one line in gds.yaml and 18 steps in Tiny Tapeout’s action. These are the ones you need to know:
- “Fetch verilog and build config” runs
tt_tool.py --create-user-config. It readsinfo.yaml, checks that every file insource_filesexists insrc/, and turns your tile size and top module into LibreLane’s configuration. Aninfo.yamlproblem stops the job here, within the first minute, with a line that startsError loading .../info.yaml:. - “Make GDS with LibreLane” runs the whole flow: lint, synthesis with Yosys, floorplan, placement, clock tree, routing, and LibreLane’s own DRC, LVS and antenna checks. At the
ttsky26dtag the action installs LibreLane 3.0.14 and runs it in LibreLane’s Docker image. A design that doesn’t fit its tiles, or that has an error Yosys or the linter catches, stops here. - “Linter output”, “Yosys warnings”, “Routing summary” and “Cell usage summary” write tables to the run’s summary page, and “Publish build logs” uploads the whole run folder as
GDS_logs. “Linter output” and “Publish build logs” run even after an earlier step has failed, and when the build stopped early, “Linter output” prints an error of its own about a log file that doesn’t exist. - “Prepare tt_submission artifact” collects the GDS, the LEF, the gate-level netlist and a
pdk.jsonnaming the PDK commit, which is what the next three jobs download.
The routing summary’s two numbers, utilisation and wire length, come from two files in GDS_logs, and in Lab 03 you find them there. In sentry’s green run on Nov 16, the run folder also held a manufacturability report that said Passed for antenna, LVS and DRC, so the layout had been checked once before precheck started.
precheck
precheck downloads tt_submission, installs the PDK at the commit Tiny Tapeout pins for it, builds its own Magic and KLayout with Nix, and runs precheck.py from Tiny Tapeout’s support tools. It passed in the three runs whose logs we read (two of protocol-emulator’s, and sentry’s 43796948508), which is what you’d expect when LibreLane has already run DRC on the same layout. It matters far more to the analog version of this course, where you draw the layout yourself. Its reports are uploaded as precheck_reports.
gl_test
gl_test checks out your repository, copies the gate-level netlist from tt_submission into test/gate_level_netlist.v, installs Tiny Tapeout’s own build of Icarus Verilog 13.0 and the packages in your test/requirements.txt, and runs your test again with GATES=yes make. That switch, in test/Makefile, compiles the netlist and the sky130 standard-cell models instead of your RTL. The step ends with its own check:
test -f results.xml
! grep -E '<(failure|error)' results.xml
So gl_test fails for the same reasons test does, and for one more: a design that’s correct in RTL simulation and wrong once it’s made of real cells. RTL and gate-level tests explains how that happens. Its waveform and results go in gatelevel_test_results.
viewer
viewer doesn’t check anything about your design. It downloads tt_submission and gds_render, writes a small page that opens Tiny Tapeout’s 3D viewer on your layout, and deploys it with GitHub Pages. It fails with a 404 until Pages is turned on, which is the first thing you fix in Lab 01. On the ttsky26d tag a re-run of a failed viewer fails again, for a reason Reading a workflow file explains, so after turning Pages on you start a new run instead, with Run workflow or a push.
What green means in this course
Tiny Tapeout says that “Only the GDS action needs to be green to submit your design”, and that for precheck “All the checks need to be green to submit to the chip”. It doesn’t say whether a gds workflow that fails only in viewer counts as failing. This course doesn’t rely on the distinction: a workflow counts as green when every one of its jobs is, viewer included, and a lab’s “done” means all six jobs passed on a commit of yours.
Check yourself
- You push a commit that empties
titleininfo.yaml. Which of the six jobs run, and which pass?
docs and gds run and fail, both in their first minute. test runs and passes, because the testbench doesn’t read info.yaml. precheck, gl_test and viewer don’t run: they need gds, which failed.
testis green andgl_testis red, on the same commit. Name two different causes.
The design behaves differently once it’s made of cells, for example because it relies on an initial statement where it needs a reset. Or the testbench depends on something the netlist doesn’t have, such as a signal inside the design that synthesis renamed or removed.
- With cocotb 2.1.0, does “Run tests” ever reach its
check_resultsline when a test fails?
No. make runs the same check at the end of the simulation and stops with an error, so the step fails at make. The extra line runs only when make passed, and then it finds no failed tests.
Next: Lab 02, where you break your repository in five ways and read what these jobs say.