26 CI and Github Actions

26.1 Release failure decoder

A release’s Install operator step runs tercenctl operator install against a test Tercen instance, and installation fails at the first stage that goes wrong. Fixing one stage often reveals the next, so read the log of the latest run, find its stage below, and fix it before tagging again.

On the managed setup, the release check runs on the stage instance (the TERCEN_TEST_OPERATOR_URI secret), as a plain test user in the default tenant — not as your own user or team. It can only use what is open to that user: trusted registries and public images.

#	Stage	Error in the log	Cause	Fix
1	Source check	`tercen.forbidden.untrusted.git`	The GitHub organisation is not in the instance’s `tercen.trusted.git`	Ask the instance admin to add it (below)
2	Image check	`tercen.forbidden.untrusted.docker`	The image’s registry namespace (e.g. `ghcr.io/myorg/`) is not in the instance’s `tercen.trusted.docker`	Ask the admin to add it, or publish the image to a trusted namespace
3	Image pull	`reading manifest … denied` or `unable to retrieve auth token: invalid username/password: unauthorized`	The image is a private ghcr package. These are the errors ghcr returns to an anonymous request for a private package — not a bad password.	Make the package public: package page → Package settings → Danger Zone → Change visibility → Public. Verify with the check below.
4	Image pull	`manifest unknown`	The tag Tercen asks for was never pushed	Check which tag `operator.json` resolves to (see the container pin rule) and that CI pushed it
5	Test discovery	`operator.run.test.not.found`	No `tests/` (or `test/`) folder with a `*.json` test	Add a unit test (Operator Unit Tests)
6	Test comparison	`task.test.operator.bad.*`	Computed output differs from the expected files	See the entries below

Check that an image is anonymously pullable (what the test instance sees):

IMG=myorg/my_operator            # the ghcr path, without ghcr.io/ and tag
TOKEN=$(curl -s "https://ghcr.io/token?scope=repository:$IMG:pull" \
  | python3 -c "import json,sys; print(json.load(sys.stdin).get('token',''))")
curl -s -o /dev/null -w '%{http_code}\n' -H "Authorization: Bearer $TOKEN" \
  "https://ghcr.io/v2/$IMG/tags/list"
# 200 = public, 403 = private (or missing)

Seen in practice (2026-10)

Three operators in public pamgene/ repositories failed release after release for different reasons in sequence: first stage 2 (ghcr.io/pamgene/ not yet trusted on stage), then stage 3 (the packages had been created private), then stage 5 (no tests/ folder). Each stage only became visible after the previous one was fixed.

26.2 Test not found

operator.run.test.not.found

This error happens when none of the test, tests or workflow_tests have been found at the repository root. For operators, use tests/ — a test/ folder runs the tests without comparing outputs. See Operator Unit Tests.

26.3 Wrong relations

task.test.operator.bad.nRelations

This error happens when there are not as many tables (relations) between the computed and expected outputs.

26.4 Wrong nCols / nRows

task.test.operator.bad.nCols task.test.operator.bad.nRows

This error happens when there are not as many columns or rows between the computed and expected output relations.

26.5 Wrong column names

task.test.operator.bad.column.names

This error happens when the computed and expected output relations do not have the exact same column names.

Maybe you’ve added or renamed a column in the latest version of the operator? In that case, the reference table should be updated accordingly.

26.6 Wrong column type

task.test.operator.bad.column.type

Check that .ri and .ci factors are output as integers in your operators.
If another factor (for example, a cluster ID), tercen test will expect is to be a double. In that case, you need to provide a schema file. If you use tim to genenerate your test, you can use the XXX argument to the build_test_data function.

26.7 Wrong values

task.test.operator.bad.value

This error occurs when a value is different between the reference table and the computed table. It gives you the row number and both values to help finding the issue.

26.8 Wrong correlation

task.test.operator.bad.correlation

This error occurs when the correlation between the reference table and the computed table values is not high enough.

26.9 Untrusted git

tercen.forbidden.untrusted.git

This error occurs when you try to install an operator from an untrusted GitHub organisation. The organisation in which you develop your operator should be added to your Tercen instance configuration file.

# CI and Github Actions ## Release failure decoder A release's **Install operator** step runs `tercenctl operator install` against a test Tercen instance, and installation fails at the **first** stage that goes wrong. Fixing one stage often reveals the next, so read the log of the latest run, find its stage below, and fix it before tagging again. On the managed setup, the release check runs on the **stage** instance (the `TERCEN_TEST_OPERATOR_URI` secret), as a plain test user in the default tenant — not as your own user or team. It can only use what is open to that user: trusted registries and public images. | # | Stage | Error in the log | Cause | Fix | |---|---|---|---|---| | 1 | Source check | `tercen.forbidden.untrusted.git` | The GitHub organisation is not in the instance's `tercen.trusted.git` | Ask the instance admin to add it ([below](#untrusted-git)) | | 2 | Image check | `tercen.forbidden.untrusted.docker` | The image's registry namespace (e.g. `ghcr.io/myorg/`) is not in the instance's `tercen.trusted.docker` | Ask the admin to add it, or publish the image to a trusted namespace | | 3 | Image pull | `reading manifest … denied` or `unable to retrieve auth token: invalid username/password: unauthorized` | The image is a **private** ghcr package. These are the errors ghcr returns to an anonymous request for a private package — not a bad password. | Make the package public: package page → **Package settings** → **Danger Zone** → **Change visibility** → Public. Verify with the check below. | | 4 | Image pull | `manifest unknown` | The tag Tercen asks for was never pushed | Check which tag `operator.json` resolves to (see [the container pin rule](../02-operator-development/8-ci.qmd)) and that CI pushed it | | 5 | Test discovery | `operator.run.test.not.found` | No `tests/` (or `test/`) folder with a `*.json` test | Add a unit test ([Operator Unit Tests](../02-operator-development/13-unit-tests.qmd)) | | 6 | Test comparison | `task.test.operator.bad.*` | Computed output differs from the expected files | See the entries below | **Check that an image is anonymously pullable** (what the test instance sees): ```bash IMG=myorg/my_operator # the ghcr path, without ghcr.io/ and tag TOKEN=$(curl -s "https://ghcr.io/token?scope=repository:$IMG:pull" \ | python3 -c "import json,sys; print(json.load(sys.stdin).get('token',''))") curl -s -o /dev/null -w '%{http_code}\n' -H "Authorization: Bearer $TOKEN" \ "https://ghcr.io/v2/$IMG/tags/list" # 200 = public, 403 = private (or missing) ``` ::: {.callout-note} ## Seen in practice (2026-10) Three operators in public `pamgene/` repositories failed release after release for different reasons in sequence: first stage 2 (`ghcr.io/pamgene/` not yet trusted on stage), then stage 3 (the packages had been created private), then stage 5 (no `tests/` folder). Each stage only became visible after the previous one was fixed. ::: ## Test not found `operator.run.test.not.found` This error happens when none of the `test`, `tests` or `workflow_tests` have been found at the repository root. For operators, use `tests/` — a `test/` folder runs the tests without comparing outputs. See [Operator Unit Tests](../02-operator-development/13-unit-tests.qmd). ## Wrong relations `task.test.operator.bad.nRelations` This error happens when there are not as many tables (relations) between the computed and expected outputs. ## Wrong nCols / nRows `task.test.operator.bad.nCols` `task.test.operator.bad.nRows` This error happens when there are not as many columns or rows between the computed and expected output relations. ## Wrong column names `task.test.operator.bad.column.names` This error happens when the computed and expected output relations do not have the exact same column names. Maybe you've added or renamed a column in the latest version of the operator? In that case, the reference table should be updated accordingly. ## Wrong column type `task.test.operator.bad.column.type` * Check that .ri and .ci factors are output as integers in your operators. * If another factor (for example, a cluster ID), tercen test will expect is to be a double. In that case, you need to provide a schema file. If you use tim to genenerate your test, you can use the XXX argument to the build_test_data function. ## Wrong values `task.test.operator.bad.value` This error occurs when a value is different between the reference table and the computed table. It gives you the row number and both values to help finding the issue. ## Wrong correlation `task.test.operator.bad.correlation` This error occurs when the correlation between the reference table and the computed table values is not high enough. ## Untrusted git `tercen.forbidden.untrusted.git` This error occurs when you try to install an operator from an untrusted GitHub organisation. The organisation in which you develop your operator should be added to your Tercen instance configuration file.