README

A generic, config-only Drupal recipe that provides a "playbooks" framework for running ordered GitLab pipelines — a Drupal-native replacement for Mattermost Playbooks. There is no custom PHP: the entire runtime is expressed as content, ECA models, and Views.

Adding a new playbook is pure content entry. No module, no code.

What you get

• Four node types (definitions and runtime data).
• Five ECA models that render the run page, serve the live status fragment, start a step's GitLab pipeline, poll running pipelines on cron, and gate access.
• Two Views used by the page and the cron poller.
• A run page with an HTMX polling region (via eca_htmx) that refreshes the step statuses every few seconds without a full page reload. The polled fragment is served by an ECA Endpoint response — no custom controller.

Data model

Definitions (content)

Definitions are content, not config entities. This is a deliberate decision to honor the zero-PHP constraint:

• A custom config entity type would require a PHP module to declare it.
• A custom simple-config object would require a PHP module to ship its schema.

Modeling definitions as node types keeps everything pure config to install, and makes "adding a playbook" a content-authoring task that any editor can do through the standard node UI.

playbook_step fields:

• field_playbook — reference to the parent playbook.
• field_weight — the step order.
• field_gitlab_instance — the GitLab server config entity ID.
• field_project_id — the GitLab project ID.
• field_trigger_id — the pipeline trigger ID (or use field_pipeline_ref).
• field_pipeline_ref — optional pipeline ref.
• field_variables — optional pipeline variables.
• field_auto_advance — whether the next step starts automatically on success.

Runtime (content)

run_step fields:

• field_run — reference to the playbook_run.
• field_step — reference to the playbook_step definition.
• field_status — pending / running / success / failed.
• field_pipeline_id — the GitLab pipeline ID created by the trigger.
• field_web_url — the GitLab pipeline deep link.
• field_started / field_finished — timestamps.

ECA models

The polled fragment is served by ECA Endpoint, not by eca_htmx

eca_htmx only provides the polling region (eca_htmx_poll). The fragment that HTMX swaps in is returned by an ordinary ECA Endpoint response event (gitlab_playbooks_status). The EndpointResponseEvent already implements RenderEventInterface, so it can return the render array that the render actions build — there is no need for a dedicated HTMX response event, and none is added here.

Endpoints

Install

drush recipe recipes/gitlab-playbooks
drush cache:rebuild

This installs the required modules (including gitlab_api and its eca_gitlab_api submodule, which requires gitlab_api 3.0.x or newer), the node types and fields, the Views, and the ECA models.

Configure a GitLab server

The GitLab API integration needs at least one configured GitLab server. Create one at Administration » Configuration » Web services » GitLab API, and use its machine name in each step's field_gitlab_instance.

How to define a playbook

1. Create a Playbook node, e.g. "Deploy Service".
2. Create one Playbook Step node per step, each referencing the playbook via field_playbook, with a field_weight for ordering and the GitLab field_gitlab_instance, field_project_id, and field_trigger_id.
3. To run it, create a Playbook Run node referencing the playbook, then create a Run Step node per step (referencing the run and the step definition, with field_status = pending).
4. Open /eca/playbook/run?run=RUN_ID. The first pending step shows a Start button; later steps are locked until their predecessor succeeds. The status region refreshes automatically via HTMX.

A future enhancement could auto-create the Run Step nodes from the Playbook definition via an additional ECA model triggered on Playbook Run insert — still pure config.

Constraints honored

• Zero custom PHP. Everything is YAML config plus this README.
• Reuse, not reinvent. GitLab calls use eca_gitlab_api, the polling region uses eca_htmx, and the endpoints use eca_endpoint.
• US English throughout.