Skip to content

Commit 16088cb

Browse files
brunoborgesbrunoborges
committed
docs: add CI/CD workflows section to README and create WORKFLOWS.md for detailed workflow descriptions
1 parent 5e0e139 commit 16088cb

2 files changed

Lines changed: 106 additions & 0 deletions

File tree

‎README.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -113,6 +113,12 @@ jbang https://github.com/copilot-community-sdk/copilot-sdk-java/blob/latest/jban
113113

114114
> Want to add your project? Open a PR!
115115
116+
## CI/CD Workflows
117+
118+
This project uses several GitHub Actions workflows for building, testing, releasing, and syncing with the upstream SDK.
119+
120+
See [WORKFLOWS.md](WORKFLOWS.md) for a full overview and details on each workflow.
121+
116122
## Contributing
117123

118124
Contributions are welcome! Please see the [Contributing Guide](CONTRIBUTING.md) for details.

‎WORKFLOWS.md‎

Lines changed: 100 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,100 @@
1+
# Workflows
2+
3+
## Overview
4+
5+
| Workflow | Description | Triggers | Schedule |
6+
|----------|-------------|----------|----------|
7+
| [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 |
8+
| [Deploy Documentation](workflows/deploy-site.yml) | Generates and deploys versioned docs to GitHub Pages | `workflow_run` (after Build & Test), `release`, `workflow_dispatch` | — |
9+
| [Publish to Maven Central](workflows/publish-maven.yml) | Releases the SDK to Maven Central and creates a GitHub Release | `workflow_dispatch` | — |
10+
| [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 |
11+
| [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) |
12+
| [Copilot Setup Steps](workflows/copilot-setup-steps.yml) | Configures the environment for the GitHub Copilot coding agent | `push` (on self-change), `workflow_dispatch` | — |
13+
14+
---
15+
16+
## Build & Test
17+
18+
**File:** [`build-test.yml`](workflows/build-test.yml)
19+
20+
Runs on every push to `main`, on pull requests, and in merge groups. Also runs weekly on Sundays to catch regressions from dependency updates.
21+
22+
Steps:
23+
1. Checks code formatting with Spotless
24+
2. Compiles the SDK and clones the upstream test harness
25+
3. Verifies Javadoc generation
26+
4. Installs the Copilot CLI from the cloned upstream SDK
27+
5. Runs the full test suite with `mvn verify`
28+
6. Uploads test results (JaCoCo + Surefire) as artifacts for site generation
29+
30+
Ignores changes to `README.md`, `LICENSE`, and `.github/**`.
31+
32+
---
33+
34+
## Deploy Documentation
35+
36+
**File:** [`deploy-site.yml`](workflows/deploy-site.yml)
37+
38+
Builds and deploys the Maven site to GitHub Pages. Supports three publishing modes:
39+
40+
- **Snapshot** — triggered automatically after a successful Build & Test run on `main`; publishes to `/snapshot/`
41+
- **Release** — triggered on `release` publication; publishes to `/vX.Y.Z/` and `/latest/`
42+
- **Manual** — allows building docs for a specific version tag, optionally publishing as `latest`, or rebuilding all versions
43+
44+
Only one deployment runs at a time (`concurrency: pages`).
45+
46+
---
47+
48+
## Publish to Maven Central
49+
50+
**File:** [`publish-maven.yml`](workflows/publish-maven.yml)
51+
52+
Manual-only workflow that performs a full release:
53+
54+
1. Determines release and next development versions (auto-derived from `pom.xml` or manually specified)
55+
2. Updates `CHANGELOG.md`, `README.md`, and `jbang-example.java` with the release version
56+
3. Injects the upstream sync commit hash from `.lastmerge` into the changelog
57+
4. Runs `mvn release:prepare` and `mvn release:perform` to deploy to Maven Central
58+
5. Creates a GitHub Release with auto-generated notes
59+
6. Moves the `latest` git tag forward
60+
7. Triggers the Deploy Documentation workflow
61+
8. Rolls back the documentation commit if the release fails
62+
63+
---
64+
65+
## Weekly Upstream Sync
66+
67+
**File:** [`weekly-upstream-sync.yml`](workflows/weekly-upstream-sync.yml)
68+
69+
Runs every Monday at 10:00 UTC. Clones the official `github/copilot-sdk` repository and compares `HEAD` against the commit hash stored in `.lastmerge`.
70+
71+
If new commits are found:
72+
1. Closes any previously open `upstream-sync` issues
73+
2. Creates a new issue with a summary of upstream changes
74+
3. Assigns the issue to `copilot-swe-agent` for automated porting
75+
76+
If no changes are found, any stale open `upstream-sync` issues are closed.
77+
78+
---
79+
80+
## Weekly Upstream Sync (Agentic Workflow: Experimental)
81+
82+
**File:** [`weekly-upstream-sync.lock.yml`](workflows/weekly-upstream-sync.lock.yml)
83+
84+
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.
85+
86+
> **Do not edit this file directly.** Edit the `.md` source and run `gh aw compile`.
87+
88+
---
89+
90+
## Copilot Setup Steps
91+
92+
**File:** [`copilot-setup-steps.yml`](workflows/copilot-setup-steps.yml)
93+
94+
Configures the development environment for the GitHub Copilot coding agent (`copilot-swe-agent`). The job **must** be named `copilot-setup-steps` to be recognized.
95+
96+
Sets up:
97+
- Node.js 22
98+
- JDK 17 (Temurin)
99+
- `gh-aw` CLI extension
100+
- Maven cache

0 commit comments

Comments
 (0)