Add the Playwright workflow template to the LibreCode catalog

[vitormattos]

Context

LibreCode keeps organization workflow templates in this repository.

The Playwright workflow should follow the same upstream adaptation model already used by the catalog: immutable upstream source, explicit LibreCode patch, reproducible render, and normal catalog validation.

LibreSign is validating the current Nextcloud Playwright E2E architecture in a separate proof of concept. The result of that work will show which changes are generic and which changes must stay inside the application repository.

Goal

Add the upstream Playwright workflow template to the LibreCode workflow catalog.

Keep the resulting workflow close to the current Nextcloud template so developers who already know Nextcloud CI see a familiar structure in LibreCode projects.

The organization template must stay generic. Do not add LibreSign runtime setup to it.

Required implementation

Follow the documented upstream workflow process in this repository.

The implementation must:

1. add the Playwright upstream source to upstream/sources.json;
2. vendor the immutable source under upstream/vendor/nextcloud/;
3. add the rendered template definition to upstream/templates.json;
4. add local template metadata;
5. add a patches/nextcloud/playwright.yml.patch only for LibreCode-wide differences that are required;
6. render the final workflow under workflow-templates/;
7. run the existing upstream, render, policy, and repository validation.

Do not manually maintain a copied workflow outside this model.

Generic workflow responsibilities

Keep the workflow responsible for generic CI tasks only.

This can include:

• checkout;
• Node and package-manager setup;
• dependency installation;
• application build;
• Playwright browser setup;
• Playwright execution;
• reports and artifacts;
• summary status;
• sharding support when provided by the upstream template;
• generic LibreCode workflow security and policy requirements.

Do not add product runtime setup to the organization template.

LibreCode patch rules

Only add a LibreCode patch when the organization needs a real difference from upstream.

Keep each change small and explain why it is needed.

Possible organization-level changes must be evaluated against the existing catalog rules. Examples include:

• LibreCode runner conventions;
• workflow security policy;
• action pinning policy;
• catalog compatibility;
• organization-wide trigger or artifact conventions.

Do not add a patch only to make LibreSign work.

If a difference is needed only by LibreSign, it belongs in the LibreSign consumer patch or LibreSign test bootstrap.

Consumer contract

The final template must work with application-owned Playwright setup.

A consumer should be able to keep project-specific files such as:

playwright.config.ts
playwright/start-nextcloud-server.mjs

The consumer owns:

• required Nextcloud apps;
• application-specific occ commands;
• application runtime tools;
• PHP or OS packages needed only by that application;
• test services used only by that application;
• product-specific readiness checks.

The organization workflow should call the project's npm/Playwright contract instead of knowing these details.

Consumer patch contract

Consumer repositories may keep a local workflow patch when they need a small workflow-level difference.

Use the existing consumer pattern:

.github/workflows/playwright.yml
.github/workflows/playwright.yml.patch

Prefer application configuration and bootstrap code before adding consumer workflow patch logic.

Do not move application setup into the organization template only to avoid a consumer patch.

Playwright npm contract

Keep the template compatible with a simple consumer contract based on package scripts.

At minimum, support the upstream expectations for:

• running Playwright;
• installing Playwright browsers when required;
• building the application before the test job.

Do not add LibreSign-only npm script names.

Sharding

Keep upstream sharding support if it is part of the current upstream workflow.

Do not force every consumer to use more than one shard.

The consumer must be able to choose a suitable shard count without changing the generic workflow architecture.

Reports

Preserve the upstream report model where practical.

The generic workflow should keep Playwright failure output useful and should upload the reports expected by the upstream template.

Do not add LibreSign-specific logs or artifact paths to the generic workflow.

Validation

Run the normal catalog checks.

At minimum verify:

• immutable upstream source verification;
• rendered template reproducibility;
• patch application;
• unit tests for catalog tooling;
• workflow policy checks;
• actionlint/zizmor checks where already used by the repository;
• REUSE compliance.

Also verify that the rendered workflow can be synchronized into a consumer that has a local .yml.patch.

Documentation

Do not duplicate the general upstream workflow documentation.

Add only the Playwright-specific consumer contract if the generic documentation does not already cover it.

Document:

• required package scripts;
• where project-specific Playwright server setup belongs;
• that application runtime dependencies stay in the consumer;
• how a consumer can use a small local workflow patch.

Out of scope

Do not:

• add LibreSign Java, JSignPdf, PDFtk, OpenSSL, Mailpit, or app setup to the template;
• add another workflow distribution model;
• replace materialized consumer workflows with remote reusable-workflow callers;
• change the catalog architecture;
• redesign the Playwright tests of any consumer;
• add application-specific health checks to the generic workflow.

Done when

• Playwright is declared as an upstream-derived workflow in the catalog.
• The upstream source is immutable and verified.
• The rendered workflow is reproducible.
• LibreCode changes are represented by explicit patches.
• The template stays generic.
• The Playwright consumer contract is documented where needed.
• Consumer .yml.patch support still works.
• Normal catalog validation passes.
• No LibreSign-specific runtime setup is present in the organization template.