diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml new file mode 100644 index 00000000..b1cd8270 --- /dev/null +++ b/.github/workflows/release.yml @@ -0,0 +1,158 @@ +name: Release + +on: + push: + tags: + - 'v*' + +permissions: + contents: write + +env: + DOCKER_IMAGE: agentstration/agentstration + +concurrency: + group: release-${{ github.ref }} + cancel-in-progress: false + +jobs: + validate-and-release: + name: Validate and publish prerelease + runs-on: ubuntu-latest + timeout-minutes: 60 + steps: + - name: Check out tagged revision + uses: actions/checkout@v7 + with: + fetch-depth: 0 + - name: Set up .NET + uses: actions/setup-dotnet@v6 + with: + global-json-file: global.json + - name: Validate tag and release notes + id: version + shell: pwsh + run: | + $version = (dotnet msbuild src/Agentstration.Web/Agentstration.Web.csproj -nologo -getProperty:Version).Trim() + if ($version -notmatch '^0\.1\.0-alpha\.\d+$') { + throw "Only the 0.1.0 alpha release line is enabled; resolved version was '$version'." + } + if ($env:GITHUB_REF_NAME -ne "v$version") { + throw "Tag '$env:GITHUB_REF_NAME' does not match product version 'v$version'." + } + $notes = "docs/releases/$version.md" + if (-not (Test-Path -LiteralPath $notes)) { + throw "Release notes '$notes' are missing." + } + "version=$version" >> $env:GITHUB_OUTPUT + "notes=$notes" >> $env:GITHUB_OUTPUT + - name: Require a commit from main + run: | + git fetch origin main + git merge-base --is-ancestor "$GITHUB_SHA" origin/main + - name: Restore + run: dotnet restore Agentstration.slnx -p:NuGetAudit=true -p:NuGetAuditMode=all + - name: Build + run: dotnet build Agentstration.slnx --configuration Release --no-restore + - name: Test + run: dotnet test Agentstration.slnx --configuration Release --no-build + - name: Restore autonomous AEP SDK + run: dotnet restore aep/Aep.slnx -p:NuGetAudit=true -p:NuGetAuditMode=all + - name: Build autonomous AEP SDK + run: dotnet build aep/Aep.slnx --configuration Release --no-restore + - name: Test autonomous AEP SDK + run: dotnet test aep/Aep.slnx --configuration Release --no-build + - name: Publish framework-dependent applications + shell: pwsh + run: | + $version = '${{ steps.version.outputs.version }}' + $server = "artifacts/agentstration-server-$version" + $workplace = "artifacts/agentstration-workplace-$version" + dotnet publish src/Agentstration.Web/Agentstration.Web.csproj --configuration Release --no-restore --no-build -p:UseAppHost=false --output $server + dotnet publish src/Agentstration.Workplace.Web/Agentstration.Workplace.Web.csproj --configuration Release --no-restore --no-build -p:UseAppHost=false --output $workplace + Copy-Item LICENSE "$server/LICENSE" + Copy-Item LICENSE "$workplace/LICENSE" + Copy-Item '${{ steps.version.outputs.notes }}' "$server/RELEASE_NOTES.md" + Copy-Item '${{ steps.version.outputs.notes }}' "$workplace/RELEASE_NOTES.md" + Compress-Archive -Path "$server/*" -DestinationPath "$server.zip" + Compress-Archive -Path "$workplace/*" -DestinationPath "$workplace.zip" + Remove-Item -Recurse -Force -LiteralPath $server, $workplace + - name: Write SHA-256 checksums + shell: pwsh + run: | + Get-ChildItem artifacts/*.zip | Sort-Object Name | ForEach-Object { + $hash = (Get-FileHash -Algorithm SHA256 -LiteralPath $_.FullName).Hash.ToLowerInvariant() + "$hash $($_.Name)" + } | Set-Content -Encoding utf8NoBOM artifacts/SHA256SUMS + - name: Require Docker Hub credentials + shell: pwsh + env: + DOCKERHUB_USERNAME: ${{ secrets.DOCKERHUB_USERNAME }} + DOCKERHUB_TOKEN: ${{ secrets.DOCKERHUB_TOKEN }} + run: | + if ([string]::IsNullOrWhiteSpace($env:DOCKERHUB_USERNAME)) { + throw "Repository secret DOCKERHUB_USERNAME is required." + } + if ([string]::IsNullOrWhiteSpace($env:DOCKERHUB_TOKEN)) { + throw "Repository secret DOCKERHUB_TOKEN is required." + } + - name: Set up QEMU + uses: docker/setup-qemu-action@v3 + - name: Set up Docker Buildx + uses: docker/setup-buildx-action@v3 + - name: Log in to Docker Hub + uses: docker/login-action@v3 + with: + username: ${{ secrets.DOCKERHUB_USERNAME }} + password: ${{ secrets.DOCKERHUB_TOKEN }} + - name: Compute container metadata + id: container-metadata + uses: docker/metadata-action@v5 + with: + images: ${{ env.DOCKER_IMAGE }} + tags: | + type=raw,value=${{ steps.version.outputs.version }} + type=raw,value=alpha + labels: | + org.opencontainers.image.version=${{ steps.version.outputs.version }} + org.opencontainers.image.licenses=Apache-2.0 + - name: Build and push multi-platform image + id: container + uses: docker/build-push-action@v6 + with: + context: . + file: Dockerfile + platforms: linux/amd64,linux/arm64 + push: true + tags: ${{ steps.container-metadata.outputs.tags }} + labels: ${{ steps.container-metadata.outputs.labels }} + provenance: true + sbom: true + cache-from: type=gha + cache-to: type=gha,mode=max + - name: Record container image provenance + shell: pwsh + run: | + @( + "image=docker.io/${{ env.DOCKER_IMAGE }}" + "immutableTag=${{ steps.version.outputs.version }}" + "channelTag=alpha" + "digest=${{ steps.container.outputs.digest }}" + "platforms=linux/amd64,linux/arm64" + ) | Set-Content -Encoding utf8NoBOM artifacts/container-image.txt + - name: Upload validated release artifacts + uses: actions/upload-artifact@v6 + with: + name: agentstration-${{ steps.version.outputs.version }} + path: artifacts/* + if-no-files-found: error + - name: Create GitHub prerelease + env: + GH_TOKEN: ${{ github.token }} + run: >- + gh release create "$GITHUB_REF_NAME" + artifacts/*.zip artifacts/SHA256SUMS artifacts/container-image.txt + --verify-tag + --prerelease + --title "Agentstration ${{ steps.version.outputs.version }}" + --notes-file "${{ steps.version.outputs.notes }}" diff --git a/Directory.Build.props b/Directory.Build.props index 9b2c54d3..86781696 100644 --- a/Directory.Build.props +++ b/Directory.Build.props @@ -7,6 +7,10 @@ true latest-recommended latest + 0.1.0 + alpha.1 + Agentstration + https://github.com/gbaudrit/agentstration true Apache-2.0 diff --git a/docs/contributing/github-governance.md b/docs/contributing/github-governance.md index da7ac57d..b3c5d79e 100644 --- a/docs/contributing/github-governance.md +++ b/docs/contributing/github-governance.md @@ -9,6 +9,7 @@ The repository keeps reviewable governance files in Git: - `.github/workflows/ci.yml` restores, builds, tests, verifies formatting on changed .NET files, and builds the container on Linux; - `.github/workflows/codeql.yml` scans C# on pull requests, `main`, and a weekly schedule; - `.github/workflows/dependency-review.yml` blocks pull requests that introduce known vulnerabilities of moderate severity or higher; +- `.github/workflows/release.yml` validates version tags, rebuilds and retests the product, packages the server and Workplace, and creates GitHub prereleases; - `.github/dependabot.yml` checks the root and autonomous AEP NuGet manifests plus GitHub Actions each week; - `.github/CODEOWNERS`, the pull request template, and issue forms provide lightweight contribution ownership and prompts; - `.github/rulesets/main.json` is the reproducible source definition for `main` protection. @@ -80,4 +81,22 @@ The following settings are remote and must be checked in the repository UI: After CodeQL and Dependency Review have completed successfully and their repository features are available, maintainers may add them as required checks. Keep that decision separate from the initial bootstrap so a plan limitation or first-run setup cannot deadlock `main`. -Release automation is intentionally deferred. The repository documents the intended Semantic Versioning direction but has no stabilized central product version or release tags yet. +## Product releases + +The root `Directory.Build.props` is the product-version source of truth. A release requires a matching notes file under `docs/releases/` and a tag named `v` on a commit already contained in `main`. The release workflow rejects mismatched versions and non-main commits before building artifacts. + +Docker Hub publication requires an existing `agentstration/agentstration` repository and these GitHub Actions repository secrets: + +- `DOCKERHUB_USERNAME`: the Docker Hub account allowed to push the repository; +- `DOCKERHUB_TOKEN`: a scoped Docker Hub access token with write permission. Do not store an account password. + +For example, after the release change has merged and all required checks have passed: + +```powershell +git switch main +git pull --ff-only +git tag -a v0.1.0-alpha.1 -m "Agentstration 0.1.0-alpha.1" +git push origin v0.1.0-alpha.1 +``` + +GitHub Actions then repeats restore, Release build, and tests; publishes framework-dependent server and Workplace ZIPs plus `SHA256SUMS`; pushes the server/Console image to Docker Hub for `linux/amd64` and `linux/arm64`; records its manifest digest; and creates a GitHub prerelease using the version-specific notes. Alpha releases publish the immutable version tag and the moving `alpha` channel, never `latest`. Do not move or reuse a published tag. Correct a failed release through a reviewed commit and a new prerelease identifier. diff --git a/docs/reference/versioning.md b/docs/reference/versioning.md index 05813170..22f86502 100644 --- a/docs/reference/versioning.md +++ b/docs/reference/versioning.md @@ -4,7 +4,7 @@ Several independent versions coexist in Agentstration. They must not be substitu | Version | Example | What changes it | | --- | --- | --- | -| Product version | `0.7.0` | A product release under Semantic Versioning. | +| Product version | `0.1.0-alpha.1` | A product release under Semantic Versioning. | | HTTP API version | Current unversioned `/api` routes | A breaking HTTP contract change, not every product release. | | Resource `apiVersion` | `agentstration.io/v1` | The schema of a declarative Management resource. | | Resource revision/generation | Agent generation `3` | A change to one resource instance or immutable snapshot. | @@ -13,9 +13,11 @@ Several independent versions coexist in Agentstration. They must not be substitu ## Product version -Agentstration intends to use Semantic Versioning: `MAJOR.MINOR.PATCH`, with prereleases such as `0.7.0-alpha.1`, `0.7.0-beta.1`, and `0.7.0-rc.1`. During `0.x`, public contracts remain under development. +Agentstration uses Semantic Versioning: `MAJOR.MINOR.PATCH`, with prereleases such as `0.1.0-alpha.1`, `0.1.0-beta.1`, and `0.1.0-rc.1`. During `0.x`, public contracts remain under development. -The repository currently has no central product version property and no Git release tags. This documentation records the policy without inventing or changing a current release number. +The product version is centralized in the root `Directory.Build.props`. The autonomous AEP workspace keeps its own package version under `aep/`; changing the Agentstration product version does not change the AEP protocol or packages. + +Product prereleases use annotated Git tags named `v`. Pushing a matching tag from a commit contained in `main` runs the release workflow, repeats the offline Release build and test suite, publishes framework-dependent server and Workplace archives, writes SHA-256 checksums, pushes a multi-platform server/Console image to Docker Hub, and creates a GitHub prerelease from the matching file under `docs/releases/`. A tag that disagrees with the central version or does not point into `main` fails closed. Prereleases publish an immutable version container tag and a moving channel tag such as `alpha`, but never `latest`. ## HTTP API version diff --git a/docs/releases/0.1.0-alpha.1.md b/docs/releases/0.1.0-alpha.1.md new file mode 100644 index 00000000..0a34b377 --- /dev/null +++ b/docs/releases/0.1.0-alpha.1.md @@ -0,0 +1,60 @@ +# Agentstration 0.1.0-alpha.1 + +Agentstration `0.1.0-alpha.1` is the first public product prerelease. It is intended for local evaluation and contributor feedback, not production deployment. Public contracts and generated SQLite schemas may change before a stable release. + +## Highlights + +- A self-hosted modular monolith with explicit Management, Work, and Runtime planes. +- Declarative Agents, Model Profiles, Runtime Profiles, deployments, immutable revisions, and workspace-scoped RBAC. +- Durable Work Items, Workplace Tasks and interactions, editable Flows, immutable publications, observable Runs, checkpoints, and human input. +- Schedule Triggers with durable occurrences and a reconstructible Quartz.NET SQLite projection. +- Governed Tool discovery and execution through MCP or AEP, including approval, ordered guards, durable per-attempt audit, and bounded opt-in argument retention. +- Autonomous AEP extensions for Ollama, llama.cpp, and LocalAI with provider-neutral effective capability resolution. +- Offline Pack installation and authoring with namespace isolation, deterministic builds, provenance, resource bindings, and modification-safe uninstall. +- Local accounts, tenant/workspace administration, security audit, external identity links, and principal-scoped UI preferences. +- Deterministic and SQLite defaults that work without a cloud account, remote API key, live LLM, or inference server. + +## Release artifacts + +The release publishes framework-dependent ZIP archives for: + +- `agentstration-server-0.1.0-alpha.1.zip`: the authoritative server and operations Console; +- `agentstration-workplace-0.1.0-alpha.1.zip`: the standalone end-user Workplace; +- `SHA256SUMS`: SHA-256 checksums for both archives; +- `container-image.txt`: the Docker Hub image, immutable tag, channel tag, platforms, and pushed manifest digest. + +The authoritative server and operations Console are also published as a provenance- and SBOM-enabled multi-platform image for `linux/amd64` and `linux/arm64`: + +```text +docker.io/agentstration/agentstration:0.1.0-alpha.1 +docker.io/agentstration/agentstration:alpha +``` + +The version tag is immutable release identity. The `alpha` tag is a moving prerelease channel and must not be used where reproducibility matters. No `latest` tag is published for this prerelease. + +.NET 10 is required. Extract the server archive and start it in deterministic mode: + +```powershell +$env:AI__Provider = "Deterministic" +dotnet Agentstration.Web.dll +``` + +The first Local-mode start redirects to `/bootstrap`; no default credentials exist. Start `Agentstration.Workplace.Web.dll` separately when the standalone Workplace is required. + +Or run the server image in deterministic mode: + +```powershell +docker run --rm -p 5100:8080 -e AI__Provider=Deterministic -v agentstration-data:/data agentstration/agentstration:0.1.0-alpha.1 +``` + +The image contains the authoritative server and Console, not the separately hosted Workplace. + +## Important alpha limitations + +- Generated development databases may require deletion and bootstrap after schema changes; no complete upgrade path is promised during this alpha. +- Runtime dispatch and scheduler recovery are local and SQLite-backed, not distributed. +- Flow and Tool execution is at-least-once and does not claim exactly-once external effects. +- Provider servers and models are never installed by Agentstration. Ollama, llama.cpp, and LocalAI integrations connect to existing local services. +- Pack updates, signatures, dependency resolution, and a remote Gallery remain planned. + +See the [current capabilities](../reference/current-capabilities.md), [local installation guide](../getting-started/local-installation.md), and [versioning strategy](../reference/versioning.md) for details. diff --git a/docs/site/sidebars.js b/docs/site/sidebars.js index fb893331..6ff9e9b3 100644 --- a/docs/site/sidebars.js +++ b/docs/site/sidebars.js @@ -78,6 +78,13 @@ const sidebars = { link: {type: 'doc', id: 'decisions/index'}, items: [{type: 'autogenerated', dirName: 'decisions'}], }, + { + type: 'category', + label: 'Releases', + items: [ + 'releases/0.1.0-alpha.1', + ], + }, { type: 'category', label: 'Contributing',