# Workflows

## Overview

| Workflow | Description | Triggers | Schedule |
|----------|-------------|----------|----------|
| [Build & Test](workflows/build-test.yml) | Builds, lints, and tests the Java SDK | `push` (main), `pull_request`, `merge_group`, `workflow_dispatch` | Sundays at 00:00 UTC |
| [Deploy Documentation](workflows/deploy-site.yml) | Generates and deploys versioned docs to GitHub Pages | `workflow_run` (after Build & Test), `release`, `workflow_dispatch` | — |
| [Publish to Maven Central](workflows/publish-maven.yml) | Releases the SDK to Maven Central and creates a GitHub Release | `workflow_dispatch` | — |
| [Weekly Upstream Sync](workflows/weekly-upstream-sync.yml) | Checks for new upstream commits and creates an issue for Copilot to merge | `workflow_dispatch` | Mondays at 10:00 UTC |
| [Weekly Upstream Sync (Agentic)](workflows/weekly-upstream-sync.lock.yml) | Compiled agentic workflow that executes the upstream sync via `gh-aw` | `workflow_dispatch` | Tuesdays at 08:39 UTC (scattered) |
| [Copilot Setup Steps](workflows/copilot-setup-steps.yml) | Configures the environment for the GitHub Copilot coding agent | `push` (on self-change), `workflow_dispatch` | — |

---

## Build & Test

**File:** [`build-test.yml`](workflows/build-test.yml)

Runs on every push to `main`, on pull requests, and in merge groups. Also runs weekly on Sundays to catch regressions from dependency updates.

Steps:
1. Checks code formatting with Spotless
2. Compiles the SDK and clones the upstream test harness
3. Verifies Javadoc generation
4. Installs the Copilot CLI from the cloned upstream SDK
5. Runs the full test suite with `mvn verify`
6. Uploads test results (JaCoCo + Surefire) as artifacts for site generation

Ignores changes to `README.md`, `LICENSE`, and `.github/**`.

---

## Deploy Documentation

**File:** [`deploy-site.yml`](workflows/deploy-site.yml)

Builds and deploys the Maven site to GitHub Pages. Supports three publishing modes:

- **Snapshot** — triggered automatically after a successful Build & Test run on `main`; publishes to `/snapshot/`
- **Release** — triggered on `release` publication; publishes to `/vX.Y.Z/` and `/latest/`
- **Manual** — allows building docs for a specific version tag, optionally publishing as `latest`, or rebuilding all versions

Only one deployment runs at a time (`concurrency: pages`).

---

## Publish to Maven Central

**File:** [`publish-maven.yml`](workflows/publish-maven.yml)

Manual-only workflow that performs a full release:

1. Determines release and next development versions (auto-derived from `pom.xml` or manually specified)
2. Updates `CHANGELOG.md`, `README.md`, and `jbang-example.java` with the release version
3. Injects the upstream sync commit hash from `.lastmerge` into the changelog
4. Runs `mvn release:prepare` and `mvn release:perform` to deploy to Maven Central
5. Creates a GitHub Release with auto-generated notes
6. Moves the `latest` git tag forward
7. Triggers the Deploy Documentation workflow
8. Rolls back the documentation commit if the release fails

---

## Weekly Upstream Sync

**File:** [`weekly-upstream-sync.yml`](workflows/weekly-upstream-sync.yml)

Runs every Monday at 10:00 UTC. Clones the official `github/copilot-sdk` repository and compares `HEAD` against the commit hash stored in `.lastmerge`.

If new commits are found:
1. Closes any previously open `upstream-sync` issues
2. Creates a new issue with a summary of upstream changes
3. Assigns the issue to `copilot-swe-agent` for automated porting

If no changes are found, any stale open `upstream-sync` issues are closed.

---

## Weekly Upstream Sync (Agentic Workflow: Experimental)

**File:** [`weekly-upstream-sync.lock.yml`](workflows/weekly-upstream-sync.lock.yml)

Auto-generated compiled workflow produced by `gh aw compile` from the corresponding `.md` source. This is the agentic counterpart that actually executes the upstream merge using the `gh-aw` MCP server and Copilot coding agent.

> **Do not edit this file directly.** Edit the `.md` source and run `gh aw compile`.

---

## Copilot Setup Steps

**File:** [`copilot-setup-steps.yml`](workflows/copilot-setup-steps.yml)

Configures the development environment for the GitHub Copilot coding agent (`copilot-swe-agent`). The job **must** be named `copilot-setup-steps` to be recognized.

Sets up:
- Node.js 22
- JDK 17 (Temurin)
- `gh-aw` CLI extension
- Maven cache