v0.1.0-rc1

Note

The first release candidate of v0.1.0. It requires pyTooling v10.0.0-rc3 or later and, for the extra sphinx, pyTooling.Sphinx v0.1.0-rc3 or later - both pre-releases on PyPI.

• ✨ The package pyTooling.GitLab with its metadata - a sub-namespace of pyTooling, like pyTooling.GitHub.
• ✨ GitLabError, the base exception; the requirements and the extras diagram and sphinx.
• ✨ pyTooling.GitLab.PipelineFile: a pipeline configuration file with its inputs, stages, variables, jobs, their needs, rules, parallel instances and triggers, and the keys workflow, include and default; extends, !reference tags and defaults are merged into the jobs as GitLab does; a file converts into the pyTooling.CI pipeline it defines, reading its local includes and child pipelines (#7, #10, #12, #14, #16, #18, #19, #20, #21).
• ✨ The pipeline run model: jobs, matrix instances, pipelines, downstream pipelines and pipeline groups as GitLab's REST API reports them, a client of that API for one project, and the dependencies a pipeline file's stages and needs imply (#8, #11, #13).
• ✨ Pipeline traces: a pipeline read from GitLab's REST API as a software execution trace, for OTLP/JSON and Gantt charts (#15), and the program pytooling-gitlab writing them (#17).
• ✨ The Sphinx domain glci: the directive glci:pipeline documents a pipeline file, glci:input and glci:variable its parameters; parameter tables, the interface, the dependencies and YAML excerpts summarize it, glci:pipeline-graph draws it (#22, #23, #24, #25, #26).
• 📖 The documentation, structured as pyTooling.GitHub's: data models, Sphinx domain glci, visualization, program, reports.
• ⚙️ The pipeline on pyTooling/Actions' CompletePipeline.

First release of pyTooling.GitLab, to work with GitLab CI/CD pipelines: a data model of pipeline configuration files (.gitlab-ci.yml, included files, child pipelines' files) and the pyTooling.CI pipeline they define; pipeline runs read from GitLab's REST API and their conversion into traces (OpenTelemetry's OTLP/JSON, Gantt charts), also by the program pytooling-gitlab; and the Sphinx domain glci, which documents pipeline files.

✨ New Features

• pyTooling.GitLab: the package, holding its metadata only - __version__ = "0.1.0rc1", author, copyright, license, keywords, project, documentation and issue tracker URLs (#1).
• pyTooling.GitLab.GitLabError (derived from pyTooling.CI.CIError): the base exception of the package (#5).
• pyTooling.GitLab.PipelineFile (#7): a data model of a GitLab CI/CD configuration file (.gitlab-ci.yml, an included file, a child pipeline's file), read with ruamel.yaml - the counterpart of pyTooling.GitHub's WorkflowFile. This release reads a file's stages, variables, jobs, needs, rules and the keys workflow, include and default, and builds the pipeline the file defines.
  • PipelineFile.FromFile(path) reads a file; an optional header document holding spec (separated by ---) is accepted.
  • PipelineFile.DeclaredStages (the stages key as written) and PipelineFile.Stages (declared or the default build, test, deploy, always between .pre and .post).
  • Variable: a variable of the top-level variables or of a job - Value, Description, Options, Expand.
  • Job (#10): a top-level key is a job unless it is a global keyword (RESERVED_KEYS); a key starting with a dot is a hidden job. PipelineFile.Jobs and PipelineFile.HiddenJobs keep them apart, with JobCount, ContainsJob(), IterateJobs(), IterateHiddenJobs().
  • A job's Stage (test if it names none, checked against PipelineFile.Stages), Script / BeforeScript / AfterScript, When (a pyTooling.CI.RuleOutcome, #30), AllowFailure and AllowedExitCodes, Image, Services, Environment, Tags and its Variables (#10).
  • Need (#12): an entry of a job's needs, with Kind (enumeration NeedKind): a job of the same pipeline, a job of another pipeline of the parent-child hierarchy, a job of another project's pipeline, or another project's pipeline whose status the job mirrors. Job.Needs is None without a needs key and empty for needs: []; Job.NeededJobs and Need.NeededJob resolve needs of the same pipeline to the file's jobs.
  • FromFile checks that a job needs only jobs of the file (an optional need may name a missing one) and that the jobs don't need each other in a cycle (#12).
  • Rule (#14): a rule of rules, kept as written, not evaluated - Condition (if), Changes and CompareTo, Exists, and When, AllowFailure and Variables applying if it matches; Job.Rules.
  • Workflow (#14): the workflow key - the pipeline's Name and its Rules; PipelineFile.Workflow.
  • Include (#16): an entry of include - Kind (enumeration IncludeKind: local, project, remote, template, component), Location as written, Files and Ref of another project, the Inputs it passes and its Rules; PipelineFile.Includes. The included files aren't read.
  • Default (#16): the default key - Image, Services, Tags, BeforeScript, AfterScript, also read from the deprecated global keywords unless default sets them; PipelineFile.Default.
  • A job's keys are merged as GitLab merges them, before the job is built (#18): !reference tags are replaced by what they refer to (a referred list is spliced into a list, nesting up to MAX_REFERENCE_DEPTH = 10); extends deep-merges the extended jobs in order, then the job's own keys, per GitLab's merge rules (up to MAX_EXTENDS_DEPTH = 11 levels, a cycle is an error; Job.Extends keeps the names); a job gets the keys of default it doesn't set, unless inherit.default says otherwise. Every key keeps the line it is written at.
  • Job.Unresolved (#18): in a file including other files, a job may extend or refer to jobs of the included files, which aren't read; the job is built from what the file has, and Unresolved names what it lacks. A file including no files must have everything it refers to.
  • Parallel (#19): a job's parallel - a Count, or a Matrix; Combinations holds one combination per instance in GitLab's order, InstanceNames the names GitLab gives the instances (test 1/3, deploy: [aws, app1]); Job.Parallel, and Need.Parallel for needs:parallel:matrix.
  • Trigger (#19): a job's trigger - a child pipeline's files as Includes, or another project's Project and Branch; Strategy (enumeration TriggerStrategy: depend, mirror), IsChildPipeline; Job.Trigger. IncludeKind.Artifact and Include.ArtifactJob include a job's artifact (a dynamic child pipeline).
  • Input (#20): an input of the header's spec:inputs - Type (enumeration InputType), Default, Required, Description, Options, Regex, conditional Rules; PipelineFile.Inputs and PipelineFile.Description. A job's inputs (GitLab 18.10) are Inputs too; Job.Inputs. A default is checked against the type and the options.
  • A stage or a needed job interpolating an input ($[[ inputs.stage ]]) is known when the file is included only, so it isn't checked against the stages or the jobs (#20).
  • PipelineFile.ToPipeline(resolver=None, depth=None) (#21): the pyTooling.CI pipeline a file defines, as pyTooling maps GitLab CI onto it - a job becomes a DefinedJob, a job with parallel a DefinedMatrix of DefinedMatrixJobs, a trigger job a DefinedWorkflow (DefinedMatrixWorkflow per instance); DefinedPipeline is named by workflow:name or the file's name. Stage order implies needs unless needs replaces them; matrix instances are named as GitLab names them (test: [3.14, linux], test 1/3); every element links back to its job by DefinitionMixin.Definition. Each element carries one pyTooling.CI.Rule per rule of its job - the rule's if, its when (else the job's, else on_success), and changes, compare_to, exists, allow_failure, variables as key-value-pairs; a job with when but no rules gets one rule without condition; workflow:rules are the pipeline's rules (#30).
  • IncludeResolver(root) (#21): reads local includes from a repository's directory, each file once; PipelineFile.FromFile(path, resolver) then resolves extends and !reference into the included files. A trigger job's child pipeline is expanded into its workflow when the resolver reads its files, limited by depth.
  • Every element knows its Parent, its PipelineFile, its Line and its Location (.gitlab-ci.yml:42) (#10); PipelineFileError(GitLabError) carries Path and Line.
• The pipeline run model (#8, #11, #13): what GitLab's REST API reports about jobs, pipelines and downstream pipelines.
  • Status: GitLab's 13 job and pipeline statuses; an unknown value is a GitLabError whose note lists the known values. Status.ToOutcome() maps a status to pyTooling.CI's outcome.
  • Source: the 20 pipeline sources of CI_PIPELINE_SOURCE.
  • StatusMixin (status, failure reason, URL) and JobMixin (identifier, stage, allow_failure, queued duration).
  • Job(pyTooling.CI.Job, StatusMixin, JobMixin) with runner and requested runner tags, Job.Parse(json); MatrixJob for an instance of parallel:matrix or parallel: N.
  • ProjectClient(pyTooling.REST.RESTClient) (#11): a client of GitLab's REST API for one project, given by its numeric identifier or its path; apiURL reaches a self-managed instance. GetJSONArray(resourcePath, pageSize=100) reads a list GitLab answers as a JSON array, following the Link: rel="next" pages.
  • Pipeline(pyTooling.CI.Pipeline, StatusMixin, PipelineContentsMixin) (#11): identifier, project number (IID), project identifier, source, reference, commit, IsTag, queued duration; Pipeline.Parse(pipeline, jobs). Jobs are added in the order GitLab created them, matrix instances grouped below a pyTooling.CI.Matrix; a pipeline without workflow:name is na...