From 88b6b75dbd42c991cc82883bc4017c7a8cfe25e7 Mon Sep 17 00:00:00 2001 From: GitHub Copilot Date: Wed, 18 Mar 2026 15:57:42 -0400 Subject: [PATCH 1/2] Add release guidance to integration guide and remove private repo references - Add 'Releasing Your Engine' section to docs/integration-guide.md explaining that engines are consumed via GitHub Releases, with a sample workflow and guidance on what to include in the release tarball - Remove all references to the private github/agent-platform-engine-example repo from both README.md and docs/integration-guide.md Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- README.md | 3 -- docs/integration-guide.md | 63 +++++++++++++++++++++++++++++++++++++-- 2 files changed, 61 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index b583044..1e01311 100644 --- a/README.md +++ b/README.md @@ -14,8 +14,6 @@ The Copilot Engine SDK provides everything you need to build an engine that runs - **CLI** — local testing harness that simulates the platform for development - **[Integration Guide](docs/integration-guide.md)** — step-by-step guide to building an engine -> **📦 Reference Implementation** — See [`github/agent-platform-engine-example`](https://github.com/github/agent-platform-engine-example) for a complete working engine built with this SDK. - ## Installation Until this package is published to a package registry, install it directly from GitHub: @@ -242,7 +240,6 @@ Engines receive these environment variables from the platform: ## Documentation - **[Integration Guide](docs/integration-guide.md)** — step-by-step guide to building an engine from scratch -- **[Example Engine](https://github.com/github/agent-platform-engine-example)** — reference implementation ## Contributing diff --git a/docs/integration-guide.md b/docs/integration-guide.md index d9fb6a6..cac2717 100644 --- a/docs/integration-guide.md +++ b/docs/integration-guide.md @@ -6,8 +6,6 @@ This guide walks you through building a custom **engine** — a program that receives a coding task from the Copilot platform, runs an agentic loop against a repository, and streams progress back to users in real time. -> **📦 Reference Implementation** — See [`github/agent-platform-engine-example`](https://github.com/github/agent-platform-engine-example) for a complete working engine built with this SDK. - ## What Is an Engine? An engine is a program that the platform executes when a user triggers a coding task — such as assigning Copilot to an issue, requesting changes on a PR, or invoking a task via the API. The platform creates a **job**, launches your engine in a secure runner environment, and your engine does the work. @@ -896,6 +894,67 @@ async function main() { } ``` +## Releasing Your Engine + +Engines are consumed via **GitHub Releases** rather than by cloning and building the source repository. Each release should contain a self-contained tarball with everything the platform needs to run your engine: the `engine.yaml` definition and your compiled build output. + +### Creating a Release + +Tag your commit and push the tag — a GitHub Actions workflow builds the project and publishes the release automatically: + +```bash +git tag v1.0.0 +git push origin v1.0.0 +``` + +### Release Workflow + +Add a workflow that triggers on version tags, builds your engine, and attaches the artifact to a GitHub Release: + +```yaml +# .github/workflows/release.yml +name: Release + +on: + push: + tags: + - 'v*' + +permissions: + contents: write + +jobs: + release: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - uses: actions/setup-node@v4 + with: + node-version: 20 + cache: npm + + - run: npm ci + + - run: npm run build + + - name: Create release tarball + run: tar -czf engine.tar.gz engine.yaml dist/ + + - name: Create GitHub Release + uses: softprops/action-gh-release@v2 + with: + files: engine.tar.gz + generate_release_notes: true +``` + +### What to Include in the Release + +Your release artifact must include `engine.yaml` and everything it references. The `entrypoint` in `engine.yaml` is resolved as a relative path, so any files or directories it points to need to be in the tarball alongside it. For example, if your entrypoint is `node dist/index.js`, then `dist/index.js` (and any of its runtime dependencies) must be present. + +The release should be self-contained — the platform should be able to extract it and run the entrypoint without cloning the repo, installing dependencies, or building from source. + + ## Architecture Notes ### Tokens From 2d4fab7acea1b69538c1b9b9e77beb7292437b35 Mon Sep 17 00:00:00 2001 From: GitHub Copilot Date: Wed, 18 Mar 2026 16:05:42 -0400 Subject: [PATCH 2/2] docs: clarify release workflow is Node-specific and require bundled deps - Label the release workflow YAML as a Node.js/TypeScript example and note that other runtimes should substitute their own build steps and paths. - Explicitly state that engines must bundle runtime dependencies into the build output (via a bundler) or include them in the tarball, since the compiled dist/ alone may not be self-contained. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- docs/integration-guide.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/integration-guide.md b/docs/integration-guide.md index cac2717..b39f6d1 100644 --- a/docs/integration-guide.md +++ b/docs/integration-guide.md @@ -909,7 +909,9 @@ git push origin v1.0.0 ### Release Workflow -Add a workflow that triggers on version tags, builds your engine, and attaches the artifact to a GitHub Release: +Add a workflow that triggers on version tags, builds your engine, and attaches the artifact to a GitHub Release. + +> **Note:** The example below is for a Node.js/TypeScript engine. If your engine uses a different runtime (Python, Go, Rust, etc.), substitute the appropriate setup, dependency installation, and build steps, and adjust the artifact paths to match your compiled output. ```yaml # .github/workflows/release.yml @@ -952,7 +954,7 @@ jobs: Your release artifact must include `engine.yaml` and everything it references. The `entrypoint` in `engine.yaml` is resolved as a relative path, so any files or directories it points to need to be in the tarball alongside it. For example, if your entrypoint is `node dist/index.js`, then `dist/index.js` (and any of its runtime dependencies) must be present. -The release should be self-contained — the platform should be able to extract it and run the entrypoint without cloning the repo, installing dependencies, or building from source. +The release should be self-contained — the platform should be able to extract it and run the entrypoint without cloning the repo, installing dependencies, or building from source. This means your build output must include all runtime dependencies. For Node.js engines, either use a bundler (e.g., esbuild, webpack, or ncc) to produce a single self-contained file, or include the `node_modules` directory in the tarball. Other runtimes should follow their equivalent strategy — for example, Go and Rust engines can compile to a static binary, while Python engines might vendor dependencies or include a virtual environment. ## Architecture Notes