Skip to content

armgit / eve

Public Imported from GitHub
0

The Open Framework for Building Agents

docs: document Vercel Connect credentials for GitHub and Linear channels (#587)

Allen Zhou46be69e5f1d2
diff --git a/.github/workflows/e2e-local.yml b/.github/workflows/e2e-local.yml
index ebed45454..6bbc9e527 100644
--- a/.github/workflows/e2e-local.yml
+++ b/.github/workflows/e2e-local.yml
@@ -3,20 +3,45 @@ name: E2E Tests (Local)
on:
workflow_dispatch:
pull_request:
- paths:
- - "packages/eve/**"
- - "pnpm-workspace.yaml"
- - "pnpm-lock.yaml"
- - "apps/fixtures/**"
- - "e2e/**"
- - ".github/workflows/e2e-local.yml"
- - ".github/scripts/discover-e2e-fixtures.sh"
concurrency:
group: e2e-local-${{ github.ref }}
cancel-in-progress: true
jobs:
+ # The e2e matrix jobs are required status checks, so they must report on
+ # every PR. An `on.pull_request.paths` filter would leave them permanently
+ # "expected" on PRs that don't touch e2e-relevant paths, blocking merge.
+ # Instead the workflow always triggers, this job decides relevance, and the
+ # matrix jobs skip when nothing relevant changed — skipped required checks
+ # count as satisfied.
+ changes:
+ name: changes
+ runs-on: ubuntu-latest
+ outputs:
+ relevant: ${{ steps.filter.outputs.relevant }}
+ steps:
+ - name: Checkout code
+ uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+ with:
+ persist-credentials: false
+ fetch-depth: 2
+
+ - name: Check changed paths
+ id: filter
+ run: |
+ if [ "${{ github.event_name }}" != "pull_request" ]; then
+ echo "relevant=true" >> "$GITHUB_OUTPUT"
+ exit 0
+ fi
+ # HEAD is the PR merge commit; HEAD^1 is the base branch tip, so
+ # this diff is exactly the PR's changed files.
+ if git diff --name-only HEAD^1 HEAD | grep -qE '^(packages/eve/|apps/fixtures/|e2e/|pnpm-workspace\.yaml$|pnpm-lock\.yaml$|\.github/workflows/e2e-local\.yml$|\.github/scripts/discover-e2e-fixtures\.sh$)'; then
+ echo "relevant=true" >> "$GITHUB_OUTPUT"
+ else
+ echo "relevant=false" >> "$GITHUB_OUTPUT"
+ fi
+
discover-fixtures:
name: discover-fixtures
runs-on: ubuntu-latest
@@ -35,7 +60,8 @@ jobs:
e2e:
name: e2e-local (${{ matrix.name }})
runs-on: ubuntu-latest
- needs: discover-fixtures
+ needs: [changes, discover-fixtures]
+ if: needs.changes.outputs.relevant == 'true'
strategy:
fail-fast: false
matrix:
diff --git a/.github/workflows/e2e-vercel.yml b/.github/workflows/e2e-vercel.yml
index 0d53fd4b3..950c9a80b 100644
--- a/.github/workflows/e2e-vercel.yml
+++ b/.github/workflows/e2e-vercel.yml
@@ -3,20 +3,45 @@ name: E2E Tests (Vercel)
on:
workflow_dispatch:
pull_request:
- paths:
- - "packages/eve/**"
- - "pnpm-workspace.yaml"
- - "pnpm-lock.yaml"
- - "apps/fixtures/**"
- - "e2e/**"
- - ".github/workflows/e2e-vercel.yml"
- - ".github/scripts/discover-e2e-fixtures.sh"
concurrency:
group: e2e-vercel-${{ github.ref }}
cancel-in-progress: true
jobs:
+ # The e2e matrix jobs are required status checks, so they must report on
+ # every PR. An `on.pull_request.paths` filter would leave them permanently
+ # "expected" on PRs that don't touch e2e-relevant paths, blocking merge.
+ # Instead the workflow always triggers, this job decides relevance, and the
+ # matrix jobs skip when nothing relevant changed — skipped required checks
+ # count as satisfied.
+ changes:
+ name: changes
+ runs-on: ubuntu-latest
+ outputs:
+ relevant: ${{ steps.filter.outputs.relevant }}
+ steps:
+ - name: Checkout code
+ uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+ with:
+ persist-credentials: false
+ fetch-depth: 2
+
+ - name: Check changed paths
+ id: filter
+ run: |
+ if [ "${{ github.event_name }}" != "pull_request" ]; then
+ echo "relevant=true" >> "$GITHUB_OUTPUT"
+ exit 0
+ fi
+ # HEAD is the PR merge commit; HEAD^1 is the base branch tip, so
+ # this diff is exactly the PR's changed files.
+ if git diff --name-only HEAD^1 HEAD | grep -qE '^(packages/eve/|apps/fixtures/|e2e/|pnpm-workspace\.yaml$|pnpm-lock\.yaml$|\.github/workflows/e2e-vercel\.yml$|\.github/scripts/discover-e2e-fixtures\.sh$)'; then
+ echo "relevant=true" >> "$GITHUB_OUTPUT"
+ else
+ echo "relevant=false" >> "$GITHUB_OUTPUT"
+ fi
+
discover-fixtures:
name: discover-fixtures
runs-on: ubuntu-latest
@@ -35,7 +60,8 @@ jobs:
e2e:
name: e2e-vercel (${{ matrix.name }})
runs-on: ubuntu-latest
- needs: discover-fixtures
+ needs: [changes, discover-fixtures]
+ if: needs.changes.outputs.relevant == 'true'
strategy:
fail-fast: false
matrix:
diff --git a/docs/channels/github.mdx b/docs/channels/github.mdx
index f8b387dd1..d82b641e3 100644
--- a/docs/channels/github.mdx
+++ b/docs/channels/github.mdx
@@ -1,13 +1,46 @@
---
title: "GitHub"
-description: "Reach your agent from GitHub App webhooks, with @mention dispatch, PR diff context, and sandbox checkout."
+description: "Reach your agent from GitHub App webhooks, with @mention dispatch, PR diff context, sandbox checkout, and Vercel Connect credentials."
type: integration
---
-The GitHub channel lets the agent work directly on a repository. Someone `@mentions` it in an issue, PR, or review comment, and the agent answers right there in the thread, with the PR diff already in context and the repo checked out into the sandbox. It takes GitHub App webhooks at `/eve/v1/github`, checks the signature, derives auth from whoever triggered the event, and replies on the native surface. See [Channels](./overview) for the contract this builds on.
+The GitHub channel lets the agent work directly on a repository. Someone `@mentions` it in an issue, PR, or review comment, and the agent answers right there in the thread, with the PR diff already in context and the repo checked out into the sandbox. It takes GitHub App webhooks at `/eve/v1/github`, checks the signature, derives auth from whoever triggered the event, and replies on the native surface. Credentials can run through [Vercel Connect](../guides/auth-and-route-protection), which manages the GitHub App, the installation token, and inbound webhook verification, so there's no app private key or webhook secret for you to hold. See [Channels](./overview) for the contract this builds on.
+
+## Set up Connect
+
+Create a GitHub Connect client and copy its UID (e.g. `github/my-agent`), then attach this project as the trigger destination at eve's GitHub route:
+
+```bash
+npm install -g vercel@latest
+vercel connect create github --triggers
+vercel connect detach <uid> --yes
+vercel connect attach <uid> --triggers --trigger-path /eve/v1/github --yes
+```
+
+The `create` step provisions the GitHub App and a trigger destination at the default Connect path. `detach` then `attach --trigger-path /eve/v1/github` re-points the trigger at the eve GitHub route, since eve does not serve the default Connect path. `--triggers` makes Connect receive the App's webhooks, verify them, and forward them to your deployment. During registration, subscribe to `issue_comment` and `pull_request_review_comment` for mention-driven turns — the managed App defaults to `pull_request` only — and add `issues`, `pull_request`, `check_suite`, `check_run`, or `workflow_run` if you wire up their opt-in hooks. You can also create the client from the [Connect dashboard](https://vercel.com/d?to=/%5Bteam%5D/~/connect&title=Go+to+Connect).
## Add the channel
+```bash
+npm install @vercel/connect
+```
+
+```ts title="agent/channels/github.ts"
+import { connectGitHubCredentials } from "@vercel/connect/eve";
+import { githubChannel } from "eve/channels/github";
+
+export default githubChannel({
+ botName: "my-agent",
+ credentials: connectGitHubCredentials("github/my-agent"),
+});
+```
+
+`connectGitHubCredentials` returns `{ installationToken, webhookVerifier }`: eve uses the Connect-managed installation token directly for GitHub API calls, skipping its native App JWT exchange, and verifies Connect-forwarded webhooks by their Vercel OIDC signature instead of a GitHub webhook secret. Token rotation, refresh, and multi-installation tenancy stay inside Connect, so there is no `GITHUB_APP_ID`, `GITHUB_APP_PRIVATE_KEY`, or `GITHUB_WEBHOOK_SECRET` to manage.
+
+### Bring your own GitHub App
+
+To run a GitHub App you manage yourself, pass its credentials directly instead:
+
```ts title="agent/channels/github.ts"
import { githubChannel } from "eve/channels/github";
diff --git a/docs/channels/linear.mdx b/docs/channels/linear.mdx
index 170e27cd6..e7bb08b6e 100644
--- a/docs/channels/linear.mdx
+++ b/docs/channels/linear.mdx
@@ -1,13 +1,45 @@
---
title: "Linear"
-description: "Reach your agent through Linear Agent Sessions, with native Agent Activities for progress, questions, and responses."
+description: "Reach your agent through Linear Agent Sessions, with native Agent Activities for progress, questions, and responses, and Vercel Connect credentials."
type: integration
---
-The Linear channel uses Linear's Agent Session surface rather than ordinary comments. Users delegate work to the agent from Linear, eve receives `AgentSessionEvent` webhooks at `/eve/v1/linear`, and the channel replies with native Agent Activities, including `thought`, `action`, `elicitation`, `response`, and `error`. See [Channels](./overview) for the contract this builds on.
+The Linear channel uses Linear's Agent Session surface rather than ordinary comments. Users delegate work to the agent from Linear, eve receives `AgentSessionEvent` webhooks at `/eve/v1/linear`, and the channel replies with native Agent Activities, including `thought`, `action`, `elicitation`, `response`, and `error`. Credentials can run through [Vercel Connect](../guides/auth-and-route-protection), which manages the Linear app, its access token, and inbound webhook verification, so there's no API key or webhook secret for you to hold. See [Channels](./overview) for the contract this builds on.
+
+## Set up Connect
+
+Create a Linear Connect client and copy its UID (e.g. `linear/my-agent`), then attach this project as the trigger destination at eve's Linear route:
+
+```bash
+npm install -g vercel@latest
+vercel connect create linear --triggers
+vercel connect detach <uid> --yes
+vercel connect attach <uid> --triggers --trigger-path /eve/v1/linear --yes
+```
+
+The `create` step provisions the Linear app — with the `app:assignable` and `app:mentionable` scopes the agent surface needs — and a trigger destination at the default Connect path. `detach` then `attach --trigger-path /eve/v1/linear` re-points the trigger at the eve Linear route, since eve does not serve the default Connect path. `--triggers` makes Connect receive Linear's webhooks, verify them, and forward them to your deployment. During registration, subscribe to the `AgentSessionEvent` webhook category — the managed app defaults to `Comment` and `Issue` — so Linear sends `created` events when the agent is delegated or mentioned and `prompted` events when the user continues the session. You can also create the client from the [Connect dashboard](https://vercel.com/d?to=/%5Bteam%5D/~/connect&title=Go+to+Connect).
## Add the channel
+```bash
+npm install @vercel/connect
+```
+
+```ts title="agent/channels/linear.ts"
+import { connectLinearCredentials } from "@vercel/connect/eve";
+import { linearChannel } from "eve/channels/linear";
+
+export default linearChannel({
+ credentials: connectLinearCredentials("linear/my-agent"),
+});
+```
+
+`connectLinearCredentials` returns `{ accessToken, webhookVerifier }`: eve uses the Connect-managed app token for Linear GraphQL calls and verifies Connect-forwarded webhooks by their Vercel OIDC signature instead of a Linear webhook secret. Token rotation, refresh, and multi-workspace tenancy stay inside Connect, so there is no `LINEAR_AGENT_ACCESS_TOKEN` or `LINEAR_WEBHOOK_SECRET` to manage.
+
+### Bring your own Linear app
+
+To run a Linear OAuth app you manage yourself, pass its credentials directly instead:
+
```ts title="agent/channels/linear.ts"
import { linearChannel } from "eve/channels/linear";
@@ -26,9 +58,7 @@ LINEAR_WEBHOOK_SECRET=... # verifies Linear-Signature
The sample passes credentials explicitly. To rely on env vars instead, drop the `credentials` block: the access token falls back to `LINEAR_AGENT_ACCESS_TOKEN`, `LINEAR_ACCESS_TOKEN`, `LINEAR_API_KEY`, or `LINEAR_API_TOKEN`, and the webhook secret falls back to `LINEAR_WEBHOOK_SECRET`. Both fields also accept lazy resolver functions.
-## Configure Linear
-
-Create a Linear OAuth app, enable Agent Session events, and point the webhook URL at:
+Create the Linear OAuth app, enable Agent Session events, and point the webhook URL at:
```text
https://<deployment>/eve/v1/linear
diff --git a/docs/channels/slack.mdx b/docs/channels/slack.mdx
index d86758bf2..a8eeb5e73 100644
--- a/docs/channels/slack.mdx
+++ b/docs/channels/slack.mdx
@@ -11,13 +11,13 @@ The Slack channel puts your agent inside a workspace. It answers `@mentions` and
Create a Slack Connect client and copy its UID (e.g. `slack/my-agent`), then attach this project as the trigger destination at eve's Slack route:
```bash
-npm install -g vercel@latest && export FF_CONNECT_ENABLED=1
+npm install -g vercel@latest
vercel connect create slack --triggers
vercel connect detach <uid> --yes
vercel connect attach <uid> --triggers --trigger-path /eve/v1/slack --yes
```
-`FF_CONNECT_ENABLED=1` turns on the Connect commands, which are feature-flagged in the Vercel CLI today. The `create` step provisions a destination at the default Connect path. `detach` then `attach --trigger-path /eve/v1/slack` re-points the trigger at the eve Slack route, since eve does not serve the default Connect path. `--triggers` turns on Slack Event Subscriptions; without it, Slack never delivers `app_mention` or `message.im`. You can also create the client from the [Connect dashboard](https://vercel.com/d?to=/%5Bteam%5D/~/connect&title=Go+to+Connect).
+The `create` step provisions a destination at the default Connect path. `detach` then `attach --trigger-path /eve/v1/slack` re-points the trigger at the eve Slack route, since eve does not serve the default Connect path. `--triggers` turns on Slack Event Subscriptions; without it, Slack never delivers `app_mention` or `message.im`. You can also create the client from the [Connect dashboard](https://vercel.com/d?to=/%5Bteam%5D/~/connect&title=Go+to+Connect).
## Add the channel