ci-automation

Reusable CI automation for TalTech IVAR Lab open-source projects.

The first supported path validates and releases Unity Package Manager packages directly from public Git repositories. It deliberately does not publish to npm or Verdaccio.

Local validation

No runtime dependencies are required:

python3 -m ci_automation validate-unity-package \
  --workspace /path/to/repository \
  --package-path .

Pass --expected-tag v1.2.3 to verify an existing tag against the package version.

Run the tests with:

python3 -m unittest discover -s tests -v

Exercise the complete version/changelog/commit/tag path against a disposable local Git remote:

npm ci --ignore-scripts --prefix semantic-release
python3 scripts/verify_semantic_release.py

Reusable workflows

• .github/workflows/unity-package-ci.yml validates package metadata with read-only permissions.
• .github/workflows/unity-package-release-dry-run.yml analyzes the next release with read-only permissions in a disposable working clone and local Git remote.
• .github/workflows/unity-package-release.yml performs the write-capable release.

Caller repositories must pin the reusable workflow to a full commit SHA. The workflow verifies that immutable reference and uses job.workflow_sha to check out its own implementation:

jobs:
  validate:
    uses: TalTech-IVAR-Lab/ci-automation/.github/workflows/unity-package-ci.yml@0123456789abcdef0123456789abcdef01234567
    with:
      package-path: .

Use the separate dry-run workflow until the repository's branch rules, Conventional Commit history, and proposed version have been reviewed. Replace that caller with the write-capable release workflow deliberately; the caller must grant contents: write.

Compatibility forks that must retain an existing com.unity... identifier can set allow-unity-package-name: true. New TalTech packages should not.

Release behavior

The locked semantic-release runtime:

• analyzes Conventional Commits on main;
• writes v<version> Git tags and GitHub Releases;
• updates the package's package.json and CHANGELOG.md;
• commits those two generated files with [skip ci];
• creates no npm package and runs no caller package lifecycle scripts.

Dependencies are locked in semantic-release/package-lock.json. GitHub actions are pinned to full commit SHAs.

The exact .releaserc, .config/releaserc, and release.config variants searched by the locked cosmiconfig dependency, plus the package.json release key, are rejected so caller configuration cannot execute or override central policy. Caller and automation sources are checked out into separate sibling directories, checkout credentials are not persisted, and the release repository URL is bound to the checked-out caller repository rather than package metadata.

Before enabling a write release, verify that the latest existing v<version> tag is reachable from main. Repository rules must permit GitHub Actions to push the generated release commit and tag; otherwise the release will stop rather than bypass protection.

Release publication is not transactional: the generated commit is pushed before semantic-release creates the tag and GitHub Release. If a later step fails, inspect main for an untagged chore(release) commit before retrying.

Design boundary

The Python core is intentionally independent of GitHub Actions. It can be run locally today and can later be exposed as a python-ci-toolkit action without changing validation semantics. PyCI integration is useful, but not on the critical path.

See docs/release-audit.md for the initial repository audit.