Skip to content

Capability 006: Generated Pipelines

Status: Accepted

Context

A generated repository is meant to be developed further right away (mission statement). Its first push already runs the pipeline, and a red pipeline right after generation costs the developer the search for a fault that is not theirs. This capability defines which jobs pass after generation, which may fail and why, and how the generator verifies that for every profile, on both forges, for single repositories and mono-repositories.

References

Details

After generation means: repo init, then make init, then a commit of everything, pushed to the default branch. In a Go profile make init writes go.sum, in the TypeScript profile package-lock.json; the pipeline installs the dependencies from that lock file. The other profiles have no lock file to write.

Jobs that may fail after generation, each for a missing input only the developer can provide:

Job Profiles Reason Remedy
firmware-build Firmware No STM32CubeMX code in vendor/cubemx/ Generate the code with STM32CubeMX
drc, production-files-build Electronics No board outline on Edge.Cuts Draw the board outline
Image push and promotion, docs publishing, changelog, release Profiles that have them Credentials or secrets of the forge Configure the registry access and RELEASE_TOKEN

Verification levels:

Level GitLab GitHub Finds
Static gitlab-ci-local --list actionlint Syntax, expressions, script injection
Local run gitlab-ci-local act Missing tools, broken install steps, missing lock files, scan gates

The test setup completes a generated example the way a developer would before verifying it: it runs make init, adds a board outline from the generator's test data, and generates the STM32CubeMX code with the installed STM32CubeMX from a .ioc file of the test data that selects the MCU only. It then calls app_init() and app_poll() in the USER CODE sections of main.c, as src/app_c_api.h directs. Without STM32CubeMX installed, it leaves vendor/cubemx/ without code and says so.

Functional Requirements

  1. After generation, every job of every profile passes on both forges, in a single repository and in a mono-repository, except the jobs of Details, and those only for their reason.
  2. A job of Details that fails for its reason says so in its output, naming the remedy.
  3. Build, lint, and test jobs run in the CI images the generator pins, the same image for the same job on both forges; no job relies on a tool that the forge's runner happens to have installed.
  4. The generator verifies requirement 1 on the static level and the local-run level for every profile and both forges.

Non-Functional Requirements

None.

Technical Requirements

  1. A GitHub job that runs in a CI image runs JavaScript actions with that image's Node.js when act runs it; every CI image of the generator therefore includes Node.js.
  2. A job that starts containers itself, such as make lint-shell or make lint-markdown, runs on the runner, not in a CI image.

Error Handling

None.

Out of Scope

  • The tag tier and the merge-request tier; this capability covers the push to the default branch
  • Setting up credentials and secrets on the forge
  • Multi-platform images and runners other than amd64

Acceptance Criteria

  1. Every profile with ci: github, as single repositories and as one mono-repository: make github-ci-check reports no finding.
  2. Every profile with ci: gitlab, as single repositories and as one mono-repository, each child pipeline included: make gitlab-ci-check reports no finding.
  3. Every profile with ci: github, completed by the test setup: make ci-local passes every job except image push and promotion, and firmware-build where STM32CubeMX is not installed.
  4. Every profile with ci: gitlab, completed by the test setup: make ci-local passes every job except image push and promotion, and firmware-build where STM32CubeMX is not installed.
  5. Every profile without the completion of the test setup: firmware-build fails naming STM32CubeMX, drc fails naming the board outline; every other job passes as in criteria 3 and 4.
  6. C++ and Java with ci: github: every build, lint, and test job declares the image of the same job in the GitLab pipeline.

Decisions

  1. The test setup completes the examples from test data; the templates stay without placeholders. A placeholder outline or STM32CubeMX project in the templates would let a real project start from a fake board or MCU. A board outline and a .ioc file that selects the MCU only are as stable as a "Hello World". Generated STM32CubeMX code is not: a stored copy keeps building while a current STM32CubeMX generates a structure the firmware template no longer fits, so the test would stay green over the very break it should find. Consequence: the test setup generates the STM32CubeMX code on every run; verifying firmware-build locally needs STM32CubeMX and the firmware package the .ioc file names, and a failure to generate the code is reported apart from a failure of the build.
  2. Both forges run build, lint, and test jobs in the same CI images. A tool from the runner's preinstalled software has a version nobody pinned and is missing under act; GitHub's runner lacked the compiler version the C++ workflows installed. Consequence: the CI images include Node.js and exist for amd64 only; make ci-local pulls them for amd64 beforehand.
  3. repo init does not run make init. make init needs the profile's toolchain from devbox, which repo init cannot assume. Consequence: a push before make init fails for lack of lock files; a Next Step names the step.
  4. The local run is the acceptance; no forge run. act and gitlab-ci-local find most faults within minutes and without a push, but run on the host's architecture and without credentials. A test repository on each forge would cost a manual test before every release for faults that rarely change. Consequence: faults of credentials, registry, Pages, and runner architecture show only on a real repository's first push.