# 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 |
| [Codegen Check](workflows/codegen-check.yml) | Verifies that generated Java files are up-to-date with the JSON schemas | `push` (main), `pull_request`, `workflow_dispatch` | — |
| [Update @github/copilot Dependency](workflows/update-copilot-dependency.yml) | Updates the `@github/copilot` npm package, re-runs code generation, and opens a PR | `workflow_dispatch` | — |
| [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 Reference Implementation Sync](workflows/weekly-reference-impl-sync.yml) | Checks for new reference implementation commits and creates an issue for Copilot to merge | `workflow_dispatch` | Mondays at 10:00 UTC |
| [Weekly Reference Implementation Sync (Agentic)](workflows/weekly-reference-impl-sync.lock.yml) | Compiled agentic workflow that executes the reference implementation 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 reference implementation test harness
3. Verifies Javadoc generation
4. Installs the Copilot CLI from the cloned reference implementation 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 reference implementation 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 Reference Implementation Sync

**File:** [`weekly-reference-impl-sync.yml`](workflows/weekly-reference-impl-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 `reference-impl-sync` issues
2. Creates a new issue with a summary of reference implementation changes
3. Assigns the issue to `copilot-swe-agent` for automated porting

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

---

## Weekly Reference Implementation Sync (Agentic Workflow: Experimental)

**File:** [`weekly-reference-impl-sync.lock.yml`](workflows/weekly-reference-impl-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 reference implementation 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`.

---

## Codegen Check

**File:** [`codegen-check.yml`](workflows/codegen-check.yml)

Verifies that the generated Java source files in `src/generated/java/` are up-to-date with the JSON schemas distributed in the `@github/copilot` npm package.

Steps:
1. Installs the codegen dependencies from `scripts/codegen/`
2. Runs the Java code generator (`npm run generate`)
3. Fails with a diff if any generated file differs from what is committed

Run this locally with:
```bash
cd scripts/codegen && npm ci && npm run generate
```

If changes appear, commit the updated generated files.

---

## Update @github/copilot Dependency

**File:** [`update-copilot-dependency.yml`](workflows/update-copilot-dependency.yml)

Manual workflow triggered when a new version of the `@github/copilot` npm package is published. Accepts a `version` input (e.g. `1.0.25`).

Steps:
1. Updates `@github/copilot` in `scripts/codegen/package.json`
2. Re-runs the Java code generator
3. Commits the updated `package.json`, `package-lock.json`, and all regenerated Java files
4. Opens (or updates) a pull request for review

The resulting PR will be automatically validated by the **Codegen Check** workflow.

---

## 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