Metadata-Version: 2.4
Name: squidient
Version: 4.0.3
Summary: CI/CD framework for alya
Project-URL: Homepage, https://alya.gitlab.bsc.es/alya/ci-cd/squidient
Project-URL: Bug Tracker, https://alya.gitlab.bsc.es/alya/ci-cd/squidient/issues
Author-email: Damien Dosimont <damien.dosimont@gmail.com>
License-File: LICENSE.txt
Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.7
Requires-Dist: importlib-resources; python_version < '3.9'
Requires-Dist: lxml
Requires-Dist: mariasql>=5
Requires-Dist: packaging>=21.3
Description-Content-Type: text/markdown

# Squidient

Squidient is a scheduler for testing, benchmarking and deploying HPC programs on SLURM machines.

## Refreshing Workspace Data

Squidient records a fingerprint of its packaged `data/` in `version/data.json`
when `squidient init .` completes. A completed full configuration records
that fingerprint in `configuration.json.dataRevision`. Staging and monitoring stop
with exit code 1 if either differs from the installed package, including for older
workspaces without this metadata. No confirmation prompt is displayed. The check
runs before Terraform provisioning, remote connections, or job submission.
A package release that leaves `data/` unchanged does not require a refresh.

Refreshing is explicit: back up any customized workspace files and configuration
first, then run:

```sh
squidient init .
squidient configure --all
```

`init` overwrites packaged workspace files but does not regenerate
`configuration.json`. `configure --all` regenerates the configuration; reapply
your local settings as necessary. Partial reconfiguration does not mark an old
configuration as current. The check never overwrites customizations automatically.
Help and cleanup commands, including `terraform stop`, remain available.
The former `fileFormat` counter and `version/version.json` are no longer used;
legacy configurations must be refreshed before workflow execution when their
data revision cannot be established.

## MR Concurrency Checks

Each MR staging/monitoring `run` job checks the GitLab API before installing
Squidient or starting a campaign. `version:final` repeats the check before its
release-version validation. A running or canceling MR run/version job in another
pipeline makes the current job fail immediately, with the conflicting pipeline
and job identifiers. There is no waiting, automatic cancellation or write API
operation. Jobs in the same parent pipeline, including its staging and monitoring
children, are excluded so those two workflows can still run together.

The check uses `CI_API_V4_URL` and the existing `SQUIDIENT_READ_API_TOKEN`.
Pagination, response sizes and request/check durations are bounded. API failures,
invalid metadata or missing credentials prevent campaign execution. Master and
trigger workflows are unchanged. Retried child runs are detected independently
of their parent pipeline's completion status.

This is a best-effort API snapshot, not an atomic lock: simultaneous starts can
race. That risk is accepted instead of queueing campaigns or using a remote lock.
Retry a rejected job after the other campaign finishes. TestPyPI publication is
automatic after successful validations for eligible version-changing MRs.

## CI Report Comments

The three `post` jobs delegate MR comments to Taskmaster's declared `task=comment`
input. The helper sends a JSON `inputs` object, never arbitrary pipeline variables.
Define `TASKMASTER_PROJECT_ID` and `TASKMASTER_TOKEN` in Squidient's CI/CD settings.
The latter is a Taskmaster pipeline trigger token, not a GitLab write API token.
Mask it in job logs and make it available to the MR pipelines that need to post;
the protected write API tokens remain exclusively in Taskmaster for this operation.
`TASKMASTER_REF` optionally selects the trusted execution reference and defaults
to `master`. GitLab provides `CI_API_V4_URL` automatically.

Taskmaster selects its own write credential using the target project: Squidient
for MR staging/monitoring reports, or Alya for triggered staging reports. Titles
and report links are unchanged. No write API credential is used by the `post`
scripts. Execution jobs use `SQUIDIENT_READ_API_TOKEN` for the watchdog
and MR lock checks; triggered Alya staging jobs also use `ALYA_READ_API_TOKEN` to
watch the source Alya pipeline. Neither `ALYA_WRITE_API_TOKEN` nor
`SQUIDIENT_WRITE_API_TOKEN` is required by Squidient's CI anymore. Their use for
publishing comments is confined to Taskmaster.

The caller only submits the request; successful submission does not mean that
Taskmaster has already posted the comment. Check the indicated Taskmaster pipeline
for the publication result. Posting remains non-blocking for the Squidient
pipeline. Automatic retries are disabled to reduce duplicate comments; manually
rerunning a post job can still create duplicates. Credentials, comment bodies
and API response bodies are not printed by the submission helper.

The Gazix, Taskmaster, Alya and Squidient migrations may be merged together.
Gazix 2.0.0 must finish publishing before Taskmaster jobs can install it. Configure
Taskmaster's protected write credentials and a protected execution ref, then run
its `tools/activate_inputs.py` preflight and explicit activation after both known
master callers have migrated. This disables arbitrary pipeline-variable overrides
in Taskmaster; there is no legacy-variable fallback. Only Alya and
Squidient on the same GitLab instance are currently authorized by Taskmaster;
an explicitly configured source API URL on another instance is rejected rather
than silently posting to the wrong project.

