|
6 | 6 |
|
7 | 7 | 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. |
8 | 8 |
|
9 | | -> **📦 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. |
10 | | -
|
11 | 9 | ## What Is an Engine? |
12 | 10 |
|
13 | 11 | 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() { |
896 | 894 | } |
897 | 895 | ``` |
898 | 896 |
|
| 897 | +## Releasing Your Engine |
| 898 | + |
| 899 | +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. |
| 900 | + |
| 901 | +### Creating a Release |
| 902 | + |
| 903 | +Tag your commit and push the tag — a GitHub Actions workflow builds the project and publishes the release automatically: |
| 904 | + |
| 905 | +```bash |
| 906 | +git tag v1.0.0 |
| 907 | +git push origin v1.0.0 |
| 908 | +``` |
| 909 | + |
| 910 | +### Release Workflow |
| 911 | + |
| 912 | +Add a workflow that triggers on version tags, builds your engine, and attaches the artifact to a GitHub Release: |
| 913 | + |
| 914 | +```yaml |
| 915 | +# .github/workflows/release.yml |
| 916 | +name: Release |
| 917 | + |
| 918 | +on: |
| 919 | + push: |
| 920 | + tags: |
| 921 | + - 'v*' |
| 922 | + |
| 923 | +permissions: |
| 924 | + contents: write |
| 925 | + |
| 926 | +jobs: |
| 927 | + release: |
| 928 | + runs-on: ubuntu-latest |
| 929 | + steps: |
| 930 | + - uses: actions/checkout@v4 |
| 931 | + |
| 932 | + - uses: actions/setup-node@v4 |
| 933 | + with: |
| 934 | + node-version: 20 |
| 935 | + cache: npm |
| 936 | + |
| 937 | + - run: npm ci |
| 938 | + |
| 939 | + - run: npm run build |
| 940 | + |
| 941 | + - name: Create release tarball |
| 942 | + run: tar -czf engine.tar.gz engine.yaml dist/ |
| 943 | + |
| 944 | + - name: Create GitHub Release |
| 945 | + uses: softprops/action-gh-release@v2 |
| 946 | + with: |
| 947 | + files: engine.tar.gz |
| 948 | + generate_release_notes: true |
| 949 | +``` |
| 950 | +
|
| 951 | +### What to Include in the Release |
| 952 | +
|
| 953 | +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. |
| 954 | + |
| 955 | +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. |
| 956 | + |
| 957 | + |
899 | 958 | ## Architecture Notes |
900 | 959 |
|
901 | 960 | ### Tokens |
|
0 commit comments