generic-gitlab-cicd 0.3.2__py3-none-any.whl

generic_ci/workflows/runtime.py

@@ -0,0 +1,421 @@
+"""Execution of revision-one workflows using installed internal tools."""
+import hashlib
+import json
+import os
+from pathlib import Path
+import re
+import shutil
+import subprocess
+import sys
+import tempfile
+import tomllib
+import tarfile
+import zipfile
+from email.parser import BytesParser
+import urllib.error
+import urllib.parse
+import urllib.request
+from generic_ci.runtime import (load_config, identity, write_json, path_in, require_receipt,
+                                receipt_path, collect, materialize, commands)
+from generic_ci.dependencies import resolve_candidates
+from generic_ci.config import allowed_url
+from .ecosystems import environment, read_version, extract_version, version_key
+
+
+def git(root, *args):
+    return subprocess.check_output(['git', *args], cwd=root, text=True).strip()
+
+
+def matches(tag, release):
+    return bool(release and re.fullmatch(re.escape(release['tag']).replace(re.escape('{version}'), '.+'), tag))
+
+
+def make_plan(data, root, expected):
+    for path, sha in data['sources'].items():
+        if hashlib.sha256(path_in(root, path).read_bytes()).hexdigest() != sha:
+            raise ValueError(f'{path} changed; render and commit the pipeline again')
+    projects = data['pipeline']['projects']
+    source, tag = os.environ.get('CI_PIPELINE_SOURCE'), os.environ.get('CI_COMMIT_TAG', '')
+    event = 'release' if tag else {'merge_request_event': 'merge-request', 'push': 'push', 'web': 'manual', 'schedule': 'schedule'}.get(source)
+    if event is None:
+        raise ValueError('unsupported workflow event')
+    changed = None
+    base = os.environ.get('CI_MERGE_REQUEST_DIFF_BASE_SHA') or os.environ.get('CI_COMMIT_BEFORE_SHA', '')
+    if event in {'push', 'merge-request'} and re.fullmatch('[a-f0-9]{40}', base) and set(base) != {'0'}:
+        try:
+            changed = git(root, 'diff', '--name-only', '--no-renames', base, 'HEAD').splitlines()
+        except subprocess.CalledProcessError:
+            pass  # Missing shallow baseline conservatively selects everything.
+    selected = set(projects)
+    if changed is not None and not set(changed).intersection(data['sources']):
+        import fnmatch
+        selected = {name for name, p in projects.items() if any(
+            p['path'] == '.' or f == p['path'] or f.startswith(p['path'].rstrip('/') + '/') or
+            any(fnmatch.fnmatch(f, pat) for pat in p['watch']) or f in {'uv.lock', 'package-lock.json', 'pnpm-lock.yaml', 'bun.lock', 'pyproject.toml', 'package.json', 'pnpm-workspace.yaml'}
+            for f in changed)}
+    direct = set(selected)
+    if event == 'release':
+        selected = {name for name, p in projects.items() if matches(tag, p['release'])}
+        direct = set(selected)
+        if not selected:
+            raise ValueError('tag matches no project release')
+    else:
+        while True:
+            more = selected | {name for name, p in projects.items() if set(p['depends_on']) & selected}
+            if more == selected:
+                break
+            selected = more
+    candidates = resolve_candidates(os.environ, data['platform']['allowed_hosts'], projects)
+    if candidates and event == 'release':
+        raise ValueError('candidate overrides are forbidden in release workflows')
+    for c in candidates:
+        selected.update(c['projects'])
+    # Close over active deployment checks as well as ordinary project jobs.
+    # Overlapping deployments can activate one another, regardless of declaration order.
+    while True:
+        more = set(selected)
+        active_deployments = set()
+        for name, deployment in data['pipeline']['deployments'].items():
+            owners = {binding['from_'].split('.')[0] for binding in deployment['images']}
+            if event in deployment['workflows'] and owners & selected:
+                active_deployments.add(name)
+                if event == 'merge-request' or deployment['update'] == 'complete':
+                    more.update(owners)
+        for node in data['nodes'].values():
+            active = node['deployment'] in active_deployments if node['deployment'] else node['project'] in selected
+            if node['event'] != event or not active:
+                continue
+            for dep in node['needs']:
+                producer = data['nodes'][dep]
+                deployment = data['pipeline']['deployments'].get(node['deployment'])
+                if deployment and event == 'release' and deployment['update'] == 'partial' and producer['action'] == 'container':
+                    continue
+                if producer['project'] is not None:
+                    more.add(producer['project'])
+        if more == selected:
+            break
+        selected = more
+    plan = {**identity(expected), 'event': event, 'selected': sorted(selected), 'direct': sorted(direct), 'candidates': candidates}
+    write_json(root / '.ci-out/plan.json', plan)
+    print(json.dumps(plan, indent=2))
+
+
+def api(data, method, path, payload=None, missing=False):
+    base = os.environ['CI_API_V4_URL']
+    allowed_url(base, data['platform']['allowed_hosts'])
+    url = base.rstrip('/') + '/projects/' + urllib.parse.quote(os.environ['CI_PROJECT_ID'], safe='') + path
+    token = os.environ.get('TOOLKIT_RELEASE_TOKEN')
+    if not token:
+        raise ValueError('TOOLKIT_RELEASE_TOKEN must be a protected project access token with API access')
+    request = urllib.request.Request(url, method=method, headers={'PRIVATE-TOKEN': token, 'Content-Type': 'application/json'},
+                                     data=json.dumps(payload).encode() if payload is not None else None)
+    try:
+        with urllib.request.urlopen(request, timeout=30) as response:
+            return json.load(response)
+    except urllib.error.HTTPError as error:
+        if missing and error.code == 404:
+            return None
+        raise ValueError(f'GitLab API {method} failed with HTTP {error.code}') from None
+
+
+def validate_version(project, root, plan):
+    release = project['release']
+    directory = path_in(root, project['path'])
+    current = read_version(directory, release)
+    is_node = release['version']['file'].endswith('.json')
+    tag = release['tag'].format(version=current)
+    if plan['event'] == 'release':
+        if tag != os.environ['CI_COMMIT_TAG']:
+            raise ValueError(f'release tag must be {tag}')
+        return current
+    target = os.environ.get('CI_MERGE_REQUEST_TARGET_BRANCH_NAME')
+    if target and release['require_bump']:
+        subprocess.run(['git', 'fetch', '--no-tags', 'origin', f'+refs/heads/{target}:refs/ci/version-base'], cwd=root, check=True)
+        file = (Path(project['path']) / release['version']['file']).as_posix()
+        result = subprocess.run(['git', 'show', 'refs/ci/version-base:' + file], cwd=root, text=True, capture_output=True)
+        if result.returncode:
+            # New file is legitimate only when absent from a successfully fetched tree.
+            exists = git(root, 'ls-tree', 'refs/ci/version-base', '--', file)
+            if exists:
+                raise ValueError('cannot read target-branch version')
+        else:
+            previous = extract_version(result.stdout, release['version'])
+            if version_key(current, is_node) <= version_key(previous, is_node):
+                raise ValueError(f'bump {file}: {current} must be greater than target version {previous}')
+    subprocess.run(['git', 'fetch', '--tags', 'origin'], cwd=root, check=True)
+    for existing in git(root, 'tag', '--list').splitlines():
+        match = re.fullmatch(re.escape(release['tag']).replace(re.escape('{version}'), '(.+)'), existing)
+        if match:
+            try:
+                old = version_key(match[1], is_node)
+            except ValueError:
+                continue
+            if version_key(current, is_node) <= old:
+                raise ValueError(f'version {current} must exceed released version {match[1]}')
+    return current
+
+
+def create_release(data, project, root):
+    release = project['release']
+    if os.environ.get('CI_COMMIT_REF_PROTECTED') != 'true' or os.environ.get('CI_COMMIT_BRANCH') != release['create']['branch']:
+        raise ValueError('release creation requires the configured protected branch')
+    current = read_version(path_in(root, project['path']), release)
+    tag = release['tag'].format(version=current)
+    ref = '/repository/tags/' + urllib.parse.quote(tag, safe='')
+    existing = api(data, 'GET', ref, missing=True)
+    if existing:
+        if existing['commit']['id'] != os.environ['CI_COMMIT_SHA']:
+            raise ValueError('release tag already points to another commit; it will not be moved')
+        return {'tag': tag, 'already_exists': True}
+    validate_version(project, root, {'event': 'push'})
+    api(data, 'POST', '/repository/tags', {'tag_name': tag, 'ref': os.environ['CI_COMMIT_SHA']})
+    return {'tag': tag, 'commit': os.environ['CI_COMMIT_SHA']}
+
+
+def build_image(data, node, root, out, plan):
+    project = data['pipeline']['projects'][node['project']]
+    settings = node['settings']
+    candidates = [c for c in plan['candidates'] if node['project'] in c['projects']]
+    if candidates and (not settings['dependency_bundle'] or project['python'] is None):
+        raise ValueError('candidate image builds require the Python dependency-bundle contract; Node candidate images are not supported yet')
+    release = plan['event'] == 'release'
+    if release and os.environ.get('CI_COMMIT_REF_PROTECTED') != 'true':
+        raise ValueError('release image push requires protected tag')
+    repository = settings['repository'] or data['platform']['registries']['containers' if release else 'previews'].rstrip('/') + '/' + node['project']
+    if not release and settings['repository']:
+        repository = data['platform']['registries']['previews'].rstrip('/') + '/' + node['project']
+    allowed_url('https://' + repository.split('/')[0], data['platform']['allowed_hosts'])
+    version = read_version(path_in(root, project['path']), project['release']) if project['release'] else None
+    tag = version if release else 'ci-' + os.environ['CI_PIPELINE_ID'] + '-' + os.environ['CI_COMMIT_SHA'][:12]
+    if not re.fullmatch(r'[A-Za-z0-9_][A-Za-z0-9_.-]{0,127}', tag):
+        raise ValueError('version is not a valid container tag; configure a compatible version')
+    directory = path_in(root, project['path'])
+    image = repository + ':' + tag
+    args = ['buildah', 'build', '--iidfile', str(out / 'iid'), '--tag', image,
+            '--file', str(path_in(directory, settings['dockerfile']))]
+    for key, value in settings['build_args'].items():
+        args += ['--build-arg', key + '=' + value]
+    for key, variable in settings['secrets'].items():
+        if not re.fullmatch(r'[A-Za-z0-9_-]+', key):
+            raise ValueError('invalid build secret identifier')
+        source = Path(os.environ[variable])
+        if not source.is_file() or ',' in str(source):
+            raise ValueError('build secret must reference a file-type variable')
+        args += ['--secret', f'id={key},src={source}']
+    if settings['target']:
+        args += ['--target', settings['target']]
+    if settings['dependency_bundle']:
+        if project['python'] is None:
+            raise ValueError('dependency-bundle currently supports Python wheelhouses')
+        from generic_ci.runtime import bundle_dependencies
+        bundle = out / 'dependency-bundle'; bundle.mkdir(exist_ok=True)
+        with environment(project, {}, root, node['project'], plan['candidates'], data['platform']['allowed_hosts'], out) as resolved:
+            bundle_dependencies(resolved, directory, bundle, data['platform']['allowed_hosts'])
+        args += ['--build-context', 'ci-dependencies=' + str(bundle)]
+    args += [str(path_in(directory, settings['context']))]
+    try:
+        subprocess.run(args, cwd=root, check=True)
+        subprocess.run(['buildah', 'push', '--digestfile', str(out / 'digest'), image, 'docker://' + image], cwd=root, check=True)
+        value = (out / 'digest').read_text().strip()
+        if not re.fullmatch('sha256:[a-f0-9]{64}', value):
+            raise ValueError('Buildah push did not return a registry digest')
+        return {'image': {'repository': repository, 'tag': tag, 'digest': value, 'version': version, 'pushed': True}}
+    finally:
+        if (out / 'iid').is_file():
+            subprocess.run(['buildah', 'rmi', (out / 'iid').read_text().strip()], capture_output=True)
+
+
+def package_build(project, root, out, directory=None):
+    directory = directory or path_in(path_in(root, project['path']), project['package']['directory'])
+    dist = out / 'dist'
+    dist.mkdir(exist_ok=True)
+    if project['python'] is not None:
+        subprocess.run(['uv', 'build', '--project', str(directory), '--no-sources', '--out-dir', str(dist)], cwd=directory, check=True)
+        files = list(dist.glob('*.whl')) + list(dist.glob('*.tar.gz'))
+        if not list(dist.glob('*.whl')) or not list(dist.glob('*.tar.gz')):
+            raise ValueError('package build must produce wheel and sdist')
+        subprocess.run([sys.executable, '-m', 'twine', 'check', *map(str, files)], check=True)
+    elif project['node'] is not None:
+        # npm pack handles npm-compatible output regardless of installation manager.
+        subprocess.run(['npm', 'pack', '--pack-destination', str(dist)], cwd=directory, check=True)
+        files = list(dist.glob('*.tgz'))
+        if len(files) != 1:
+            raise ValueError('npm pack must produce exactly one package')
+    else:
+        raise ValueError('package build requires Python or Node settings')
+    # Validate the actual archive metadata, not just the source manifest.
+    expected_meta = tomllib.loads((directory / 'pyproject.toml').read_text())['project'] if project['python'] is not None else json.loads((directory / 'package.json').read_text())
+    for file in files:
+        if file.suffix == '.whl':
+            with zipfile.ZipFile(file) as archive:
+                members = [n for n in archive.namelist() if n.endswith('.dist-info/METADATA')]
+                if len(members) != 1:
+                    raise ValueError('wheel requires exactly one METADATA file')
+                metadata = BytesParser().parsebytes(archive.read(members[0]))
+                built_name, built_version = metadata['Name'], metadata['Version']
+        else:
+            with tarfile.open(file) as archive:
+                if project['node'] is not None:
+                    metadata = json.load(archive.extractfile('package/package.json'))
+                    built_name, built_version = metadata['name'], metadata['version']
+                else:
+                    members = [m for m in archive.getmembers() if len(Path(m.name).parts) == 2 and m.name.endswith('/PKG-INFO')]
+                    if len(members) != 1:
+                        raise ValueError('sdist requires root PKG-INFO')
+                    metadata = BytesParser().parsebytes(archive.extractfile(members[0]).read())
+                    built_name, built_version = metadata['Name'], metadata['Version']
+        normalize = lambda s: re.sub(r'[-_.]+', '-', s).lower()
+        if normalize(built_name) != normalize(expected_meta['name']) or built_version != expected_meta['version']:
+            raise ValueError('built package identity differs from source metadata')
+    return {'package': {'name': expected_meta['name'], 'version': expected_meta['version']}, 'files': [{'path': f.relative_to(root).as_posix(), 'artifact': f.relative_to(root).as_posix(),
+                       'sha256': hashlib.sha256(f.read_bytes()).hexdigest()} for f in files]}
+
+
+def publish(data, node, project, root, records, plan):
+    from .publication import (check_development_context, destination, release_channel, snapshot_version)
+    development = node['settings'].get('channel') == 'development'
+    if development:
+        check_development_context(plan)
+        current = None
+    else:
+        if os.environ.get('CI_COMMIT_REF_PROTECTED') != 'true' or plan['candidates'] or plan['event'] != 'release':
+            raise ValueError('publishing requires a protected release without candidate dependencies')
+        current = validate_version(project, root, plan)
+    directory = path_in(root, project['path'])
+    if node['settings']['publish_package']:
+        package_dir = path_in(directory, project['package']['directory'])
+        target = destination(project, package_dir, data['platform']['allowed_hosts'], development)
+        packages = [r for r in records if r['action'] == 'package' and r.get('project') == node['project']]
+        files = [path_in(root, f['artifact']) for r in packages for f in r['files']]
+        if len(packages) != 1 or not files:
+            raise ValueError('missing unique project package artifacts')
+        if development:
+            meta = tomllib.loads((package_dir / 'pyproject.toml').read_text())['project'] if project['python'] is not None else json.loads((package_dir / 'package.json').read_text())
+            current = snapshot_version(meta['version'], project['node'] is not None)
+            if packages[0].get('publication') != {'channel': 'development', 'destination': target}:
+                raise ValueError('development artifact destination differs from publication configuration')
+        if packages[0]['package']['version'] != current:
+            raise ValueError('built package version differs from publication version')
+        channel = 'dev' if development else release_channel(current, project['node'] is not None)
+        if project['python'] is not None:
+            subprocess.run(['uv', 'publish', '--index', target['index'], '--publish-url', target['url'], '--check-url', target['check_url'], *map(str, files)], cwd=package_dir, check=True)
+        else:
+            for file in files:
+                with tarfile.open(file) as archive:
+                    packed = json.load(archive.extractfile('package/package.json'))
+                config = packed.get('publishConfig', {})
+                channel = config.get('tag', channel)
+                subprocess.run(['npm', 'publish', str(file), '--registry', target['url'], '--tag', channel, '--ignore-scripts'], cwd=package_dir, check=True)
+        if development:
+            return {'version': current, 'publication': {'channel': 'development', 'destination': target}}
+    tag = project['release']['tag'].format(version=current)
+    existing = api(data, 'GET', '/releases/' + urllib.parse.quote(tag, safe=''), missing=True)
+    if not existing:
+        api(data, 'POST', '/releases', {'tag_name': tag, 'name': tag, 'description': 'Published by verified pipeline ' + os.environ['CI_PIPELINE_ID']})
+    return {'version': current, 'tag': tag}
+
+
+def run_job(data, key, root, expected):
+    node = data['nodes'][key]
+    out = root / '.ci-out' / key
+    out.mkdir(parents=True, exist_ok=True)
+    receipt_path(root, key).unlink(missing_ok=True)
+    if node['action'] == 'stop':
+        from .helm import deploy
+        return deploy(data, node, root, out, [], {}, stop=True)
+    plan = json.loads((root / '.ci-out/plan.json').read_text())
+    if any(plan.get(k) != v for k, v in identity(expected).items()):
+        raise ValueError('stale plan')
+    if plan['event'] != node['event']:
+        raise ValueError('job event does not match plan')
+    if node['project'] and not node['deployment'] and node['project'] not in plan['selected']:
+        print('Project not selected; no success receipt emitted')
+        return
+    if node['deployment']:
+        bound = {i['from_'].split('.')[0] for i in data['pipeline']['deployments'][node['deployment']]['images']}
+        if not bound.intersection(plan['selected']):
+            print('Deployment unaffected; no success receipt emitted')
+            return
+    records = []
+    for upstream in node['needs']:
+        producer = data['nodes'][upstream]
+        deployment = data['pipeline']['deployments'].get(node['deployment'])
+        if deployment and deployment['update'] == 'partial' and producer['action'] == 'container' and producer['project'] not in plan['selected']:
+            continue
+        records.append(require_receipt(root, upstream, expected))
+    materialize(root, records)
+    project = data['pipeline']['projects'].get(node['project'])
+    action = node['action']
+    result = {**identity(expected), 'status': 'passed', 'action': action, 'project': node['project'], 'files': []}
+    if action in {'check', 'application'}:
+        settings = node['settings']
+        directory = path_in(root, project['path'])
+        environment_vars = {'DEPLOYMENT_URL': r['url'] for r in records if 'url' in r}
+        with environment(project, settings, root, node['project'], plan['candidates'], data['platform']['allowed_hosts'], out) as record:
+            result['dependencies'] = {k: v for k, v in record.items() if k != 'interpreter'}
+            commands(settings['script'], directory, 'sh', environment_vars)
+            result['files'] = collect(root, directory, settings.get('outputs', []), out)
+    elif action == 'approve':
+        pass
+    elif action == 'version':
+        # Consumer retesting does not require bumping the consumer's version.
+        if node['project'] not in plan['direct'] and plan['event'] != 'release':
+            result['version'] = read_version(path_in(root, project['path']), project['release'])
+        else:
+            result['version'] = validate_version(project, root, plan)
+    elif action == 'create-release':
+        if node['project'] not in plan['direct']:
+            print('No direct project changes; no release created')
+            return
+        result.update(create_release(data, project, root))
+    elif action == 'container':
+        result.update(build_image(data, node, root, out, plan))
+    elif action == 'package':
+        with environment(project, {}, root, node['project'], plan['candidates'], data['platform']['allowed_hosts'], out):
+            if node['settings'].get('channel') == 'development':
+                from .publication import check_development_context, destination, rewrite_snapshot
+                check_development_context(plan)
+                package_dir = path_in(path_in(root, project['path']), project['package']['directory'])
+                target = destination(project, package_dir, data['platform']['allowed_hosts'], True)
+                with tempfile.TemporaryDirectory(prefix='generic-ci-package-') as temp:
+                    # Preserve workspace layout, generated files and prepared dependencies.
+                    # Only the copy's manifest is rewritten, including on build failure.
+                    copied = Path(temp) / 'source'
+                    shutil.copytree(root, copied, symlinks=True, ignore=shutil.ignore_patterns('.git', '.ci-out'))
+                    copied_dir = path_in(path_in(copied, project['path']), project['package']['directory'])
+                    if (copied_dir / ('package.json' if project['node'] is not None else 'pyproject.toml')).is_symlink():
+                        raise ValueError('development package manifest cannot be a symlink')
+                    rewrite_snapshot(copied_dir, project['node'] is not None, target)
+                    result.update(package_build(project, root, out, copied_dir))
+                result['publication'] = {'channel': 'development', 'destination': target}
+            else:
+                result.update(package_build(project, root, out))
+    elif action == 'publish':
+        result.update(publish(data, node, project, root, records, plan))
+    elif action == 'deploy':
+        from .helm import deploy
+        result.update(deploy(data, node, root, out, records, plan))
+    else:
+        raise ValueError(f'unknown action {action}')
+    write_json(receipt_path(root, key), result)
+
+
+def main():
+    try:
+        expected = sys.argv[-1]
+        data = load_config(expected)
+        if data.get('format') != 'workflows-v1':
+            raise ValueError('not a workflow execution configuration')
+        root = Path(os.environ.get('CI_PROJECT_DIR', '.')).resolve()
+        if sys.argv[1] == 'plan':
+            make_plan(data, root, expected)
+        elif sys.argv[1] == 'run':
+            run_job(data, sys.argv[2], root, expected)
+        else:
+            raise ValueError('expected plan or run')
+    except (ValueError, KeyError, OSError, subprocess.CalledProcessError) as error:
+        print(f'generic-ci: {error}', file=sys.stderr)
+        raise SystemExit(1) from error
+
+if __name__ == '__main__':
+    main()

generic_gitlab_cicd-0.3.2.dist-info/METADATA

@@ -0,0 +1,170 @@
+Metadata-Version: 2.4
+Name: generic-gitlab-cicd
+Version: 0.3.2
+Summary: Validated project configuration and reproducible GitLab delivery pipelines
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: pydantic<3,>=2.10
+Requires-Dist: PyYAML<7,>=6
+Requires-Dist: tomlkit<1,>=0.13
+Requires-Dist: packaging<27,>=25
+
+Testing commands and the local/E2E split: [testing — revision one](docs/testing-revision-one.md).
+
+Start with the [documentation map](docs/README.md), [AI authoring guide](docs/ai-authoring-revision-three.md), or portable [generic-ci-authoring skill](skills/generic-ci-authoring/SKILL.md).
+
+Organization defaults and Git-backed starter templates are now available: see [configuration sources — revision two](docs/configuration-sources-revision-two.md).
+
+> Feature-branch workflow interface (0.3.1): see [implemented revision-one guide](docs/workflows-revision-one.md), [configuration examples](examples/workflows), and [JSON Schema](schemas/workflows.schema.json). This is a review build with documented integration gates. Older prototype CLI commands now require `--format legacy`; existing GitLab components remain available.
+
+# Generic GitLab CI components — revision one
+
+A self-contained component repository for GitLab, including an offline-capable runtime-image factory and a generic Kubernetes Helm chart. The recommended Python entry point is `examples/uv-airgap.yml`.
+
+This is an implementation to configure and validate on your installation. It has not been run against your GitLab, Artifactory or Kubernetes cluster. Infrastructure addresses, credentials, approved base images and application deployment settings must be supplied by your organization.
+
+## Components
+
+| Component | Purpose |
+| --- | --- |
+| `workflow` | Stages, cancellation of superseded work, suppression of duplicate push/MR pipelines |
+| `task` | Language-neutral lint, test, build or verification commands; reports, caches and artifacts |
+| `uv-test` | Locked uv validation, optional Git dependency replacement and commit provenance |
+| `version-check` | PEP 440 version increase against the current target branch; tag/version matching |
+| `python-package` | Build wheel/sdist once, check metadata, retain distribution artifacts |
+| `python-publish` | Publish those artifacts to PyPI, TestPyPI, GitLab or Artifactory |
+| `container-preview-build` | Same-project MR builds restricted to a dedicated preview repository |
+| `container-build` | Rootless BuildKit build, digest metadata, optional protected-ref registry push |
+| `deploy` / `preview` | Provider-neutral command adapters with deployment locking and preview cleanup |
+| `helm-deploy` / `helm-preview` | Helm rollout with failure rollback and isolated review environments |
+| `release` | Create a GitLab release for an existing protected tag |
+
+Each YAML file documents its own typed inputs. Include components multiple times with unique job names. Secrets remain GitLab CI variables; they are never component inputs.
+
+## Bootstrap
+
+1. Import this directory into a GitLab project such as `platform/ci-components` on your own GitLab instance. Component includes cannot directly cross to an unrelated GitLab instance; mirror this repository internally.
+2. Configure the variables in `docs/airgap.md`, and supply approved internal Python, BuildKit and Helm runtime images. The repository's own pipeline uses those images. Do not switch all consumers until the runtime images are available.
+3. Adapt non-secret files under `images/python/config/`, add approved CA certificates, and review `images/python/requirements.lock`. Run `images.gitlab-ci.yml` to build the Python runtime from your internal package index and push it to Artifactory. Initial BuildKit and Python base images must already be mirrored and trusted.
+4. Run this repository's validation pipeline. Publish/tag an immutable component version, e.g. `1.0.0`. Optionally mark the project as a CI/CD Catalog resource and create a GitLab release. Consumers may pin a full commit SHA before the first release.
+5. Copy the relevant example as the consuming project's `.gitlab-ci.yml`. Replace `platform/ci-components`, the release ref and deployment placeholders.
+6. Validate the expanded pipeline with your GitLab CI Lint, then run MR, default-branch and protected-tag scenarios before enabling production publishing.
+
+Use a supported GitLab with CI/CD components and array inputs (GitLab 17+ syntax baseline). The optional native release job also requires a GitLab-compatible glab runtime; verify server/CLI compatibility. Runtime jobs target Linux container runners, not Windows shell runners.
+
+## Minimal uv project
+
+```yaml
+variables:
+  CI_DEPENDENCY_REPO: ""
+  CI_DEPENDENCY_REF: ""
+  CI_DEPENDENCY_PACKAGE: ""
+  CI_DEPENDENCY_OVERRIDES: '[]'
+
+include:
+  - component: $CI_SERVER_FQDN/platform/ci-components/workflow@1.0.0
+  - component: $CI_SERVER_FQDN/platform/ci-components/uv-test@1.0.0
+    inputs:
+      name: api-test
+      repo: $CI_DEPENDENCY_REPO
+      ref: $CI_DEPENDENCY_REF
+      package: $CI_DEPENDENCY_PACKAGE
+      overrides-json: $CI_DEPENDENCY_OVERRIDES
+```
+
+Set `PYTHON_CI_IMAGE` to your internal runtime image. Commit `uv.lock`. Put pytest and application test dependencies in the project's dependency groups. `uv-test` syncs all groups; define mutually compatible groups. Tests run with `uv run --no-sync` so uv does not undo a candidate installation.
+
+## Cross-repository dependencies
+
+For an unreleased dependency, start a pipeline with:
+
+```text
+CI_DEPENDENCY_REPO=https://gitlab.internal/team/shared-sdk.git
+CI_DEPENDENCY_REF=feature/new-api
+CI_DEPENDENCY_PACKAGE=shared-sdk
+```
+
+For several dependencies or a package in a repository subdirectory:
+
+```json
+[
+  {"repo":"https://gitlab.internal/team/sdk.git", "ref":"feature/new-api", "package":"shared-sdk"},
+  {"repo":"https://gitlab.internal/team/core.git", "ref":"0123456789012345678901234567890123456789", "package":"core-utils", "subdirectory":"packages/utils"}
+]
+```
+
+Set that array as `CI_DEPENDENCY_OVERRIDES`. Both mechanisms can be combined if package names do not overlap.
+
+The helper resolves each branch/tag to a commit, applies temporary `tool.uv.override-dependencies`, removes conflicting uv source mappings for the named distribution, re-resolves, and verifies installed `direct_url.json` commit metadata. Original pyproject and lock bytes are restored even if sync fails. A successful override run saves requested refs and actual commits as a provenance artifact. A branch can move between pipelines; use the recorded SHA for reproducible reruns.
+
+The normal path uses `uv sync --locked --all-groups`. The override path deliberately re-resolves and can change transitive dependencies; it tests candidate compatibility rather than certifying the production lock. Overrides must name an installed distribution; a typo or irrelevant package fails verification.
+
+Configure read-only Git authentication in the job's `setup` or runner credential helper. Use credential-free repository URLs. For CI_JOB_TOKEN access, allowlist the consumer project in each dependency project. Restrict the credential helper to the intended host. Do not put credentials in URLs, artifacts, images, or tracked config.
+
+Run a uv workspace from its root; its virtual environment must be `.venv` there. For independent monorepo projects, include one `uv-test` per project and use unique report/provenance paths. Custom UV_PROJECT_ENVIRONMENT layouts require adapting the helper's virtual-environment path.
+
+## Coordinated releases
+
+Candidate testing solves the validation deadlock. It does not make multiple registry publications transactional.
+
+1. Validate the application and dependency candidates together using immutable overrides.
+2. Publish the dependency's real version to the internal package repository.
+3. Update/validate the application's production lock against that registry, with overrides cleared.
+4. Build once, publish/deploy the application, then create its GitLab release.
+
+A dependency package can usually be published before the application is deployed; publishing the wheel does not deploy a running service. For stronger coordination, use an internal candidate repository and promote approved packages before deployment. Two independent GitLab projects still need an orchestration policy; this framework does not promise atomic cross-project rollback. Multi-project trigger/approval coordination is an extension point, not implemented here.
+
+The standard publish and production deploy jobs reject nonempty `CI_DEPENDENCY_*` override variables. Do not hard-code candidate inputs in a production pipeline. Preview artifacts may intentionally contain candidate dependencies; never promote those to production without a clean release validation.
+
+## Versioning, tags and releases
+
+`version-check` reads static `[project].version`. In branch/MR pipelines it fetches the current target branch and requires a strict PEP 440 increase. On tags it requires the tag suffix to match the package version. The default prefix is `v`; use `sdk-v` for independent package tags. Dynamic SCM versions require a custom command via `task`.
+
+Use change rules to restrict bump checks to meaningful package changes if documentation-only MRs should not bump a version. The default checks every selected non-default branch pipeline. `allow-new-package` explicitly permits a manifest absent from the target branch.
+
+Tags are an input to the release pipeline. Create and protect them through your established process; CI does not silently create or push tags. Package publishing and production deployment are blocking manual jobs on protected tags by default. The GitLab release runs last, using `CHANGELOG.md` or a configured notes file. Existing GitLab release retries require deliberate handling; no overwrite or package `--skip-existing` behavior hides duplicate releases.
+
+A tag check validates manifest metadata, not the version assigned by every possible custom build backend. The build defaults use static PEP 621 metadata. Custom build commands should add wheel metadata/version assertions if they derive or rewrite versions.
+
+## Monorepos and cost
+
+`examples/monorepo.yml` demonstrates independent service rules, shared dependency paths and service-specific tag names. Include every shared source/config/lock path that can affect a service; transitive dependency graph discovery is not automatic. `CI_FULL_PIPELINE=true` and schedules run full verification. Tags rebuild all package units in that example, so a release never consumes artifacts from a different pipeline.
+
+The defaults preserve stage barriers: lint → test → build → verify → publish → deploy → release. Jobs use `dependencies` only to select artifacts. No default `needs: []` bypasses validation. All enabled tests must pass before any build proceeds. Stage barriers are conservative across unrelated services; customize explicit DAG dependencies only after keeping release gates intact.
+
+Tests fail normally; only runner/system failures retry once. Deploy/publish operations never retry automatically. Superseded interruptible work can be cancelled. Use `task` cache controls for package download caches, with lockfile-derived keys; keep protected/unprotected cache separation enabled. uv's download cache is safe to rebuild and is not proof of dependency correctness.
+
+## Helm deployment
+
+Use `charts/generic-app`, `examples/helm-values.yaml`, and `docs/kubernetes.md`. Helm manages the application release; Terraform is appropriate for cluster, DNS, network and registry infrastructure outside this repository's scope.
+
+Deploy digest-pinned images from the exact build artifacts. `helm-deploy.image-map-json` maps application names to image repositories and BuildKit metadata files; the helper extracts digests into an overlay passed to Helm. One Helm release may deploy several services, or use separate releases for independently deployable services.
+
+## Validation
+
+```sh
+python -m pip install -r requirements-dev.txt
+python scripts/sync_embedded.py --check
+python -m unittest discover -s tests -v
+python tests/integration_uv.py
+helm lint charts/generic-app -f examples/helm-values.yaml --strict
+helm template smoke charts/generic-app -f examples/helm-values.yaml
+```
+
+The integration test uses local Git repositories and URL rewriting; it does not contact a real dependency host or publish anything. The lightweight component expander tests inputs, names and artifact references. It is not GitLab's server-side compiler. Do not interpret local tests as proof that a specific runner, RBAC policy, Artifactory endpoint or cluster deployment works.
+
+## Official references
+
+- GitLab components: https://docs.gitlab.com/ci/components/
+- GitLab input types: https://docs.gitlab.com/ci/inputs/
+- GitLab environment teardown: https://docs.gitlab.com/ci/environments/
+- Rootless BuildKit: https://docs.gitlab.com/ci/docker/using_buildkit/
+- GitLab releases: https://docs.gitlab.com/user/project/releases/release_cicd_examples/
+- uv overrides: https://docs.astral.sh/uv/concepts/resolution/
+- uv configuration: https://docs.astral.sh/uv/reference/settings/
+- PyPI trusted publishing: https://docs.pypi.org/trusted-publishers/using-a-publisher/
+- Helm upgrade: https://helm.sh/docs/helm/helm_upgrade/
+
+## Publishing this toolkit to PyPI
+
+The PyPI distribution is `generic-gitlab-cicd`; its CLI remains `generic-ci`. The [Publish to PyPI workflow](.github/workflows/publish.yml) uses Trusted Publishing on a published GitHub release or a manual run. See [publisher configuration and release steps](docs/pypi-release.md).

generic_gitlab_cicd-0.3.2.dist-info/RECORD

@@ -0,0 +1,21 @@
+generic_ci/__init__.py,sha256=7gpTNNcCDrmt382WW40tScoMJPUMikRufhLl4T2egXw,106
+generic_ci/__main__.py,sha256=k1ocEWawweo1qCJWNFAAvyxz3tcY13dzvCenHszij30,48
+generic_ci/cli.py,sha256=Pj6LdtwykT4mq08Trs3h0F5fABTwWCpssh9nJvdoha8,6087
+generic_ci/compiler.py,sha256=klfakk3Xoc1P8wfavm6c-cZcL7bJKw6hQw8TbDWviLo,14005
+generic_ci/config.py,sha256=rmSZJleenhz8DCHC68QGPkn4G7bomjdZP_ruCneoZIM,7745
+generic_ci/dependencies.py,sha256=9ILs48hYhW047FTC9jQs5umgfH0kQu5xA3F5yPvwaEY,9844
+generic_ci/models.py,sha256=owwvpXgJTSaoXWoKpCHHAw6OXQHG9ta6_VmgNbjzgvk,8828
+generic_ci/runtime.py,sha256=15q6YugiFKYYzV6Z3AQDr6_GGbVtF_k-QGOMd3vvMs8,27782
+generic_ci/sources.py,sha256=KcvlUjA32zdHmS6l8dmvc-zttO9GwWVwC0Or6E9FgI4,14542
+generic_ci/workflows/__init__.py,sha256=pGAo3jDFfym_rWsJ_HGTkdVzT4eL9LYZtbIJGuZ3MUI,49
+generic_ci/workflows/compiler.py,sha256=nllDE-qvf_gza8rFXzPUjxEHTfwIBG_D_JVSc9xqD0g,18806
+generic_ci/workflows/ecosystems.py,sha256=w8SlDuHd06AJOlv3JymwZE77jCnSVcFHr9S3bQVQXvo,10444
+generic_ci/workflows/helm.py,sha256=NA8JXdoaZ1n2-Nnv3-wHUwlLYAmp1oiMzUQ48lZ_M2U,9203
+generic_ci/workflows/models.py,sha256=OI5bpjND6L8jfHRATkPbyIWePuGDZl9pUk1KHZYrDN8,9879
+generic_ci/workflows/publication.py,sha256=Yit9ZbQiYGH0dgx12Qd4a2ahUNJEPiW94wmUgGDblQg,3636
+generic_ci/workflows/runtime.py,sha256=0Ng9pN74VQbXZm0F8obm9i2fpIWEIemlANnOZr6vb9w,24467
+generic_gitlab_cicd-0.3.2.dist-info/METADATA,sha256=24YZQY64cj5xmrRx1ZChzklkdklWVFzyjsx6CU3xRMI,13608
+generic_gitlab_cicd-0.3.2.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+generic_gitlab_cicd-0.3.2.dist-info/entry_points.txt,sha256=v1ZgY-7kmUo5JEC8ilNrYcjdYx2g1BClDW6l-g6KSGI,51
+generic_gitlab_cicd-0.3.2.dist-info/top_level.txt,sha256=f46-VP1dRS-uav36Uw1n9JF93l-F98flDunBGJybsxo,11
+generic_gitlab_cicd-0.3.2.dist-info/RECORD,,

generic_gitlab_cicd-0.3.2.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

generic_gitlab_cicd-0.3.2.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+generic-ci = generic_ci.cli:main

generic_gitlab_cicd-0.3.2.dist-info/top_level.txt

@@ -0,0 +1 @@
+generic_ci