[pelikhan]

ADR: ADR-74077: Declarative Connectors Replace Native Provider Integrations - Proposed, pending maintainer review; no approval is implied.

Motivation

Replace provider-specific compiler/runtime handlers with editable declarative connectors and a shared execution boundary. Keep the exposed MCP tool set small and targeted; exhaustive historical parity is not the goal.

Authoring and selection

Declarations live under .github/workflows/connectors/<id>.md and use ordinary local or reviewed pinned remote imports with uses/with. There is no built-in provider catalog, hidden fallback, generated provider bundle or compiler rebuild requirement for downstream declaration edits. The 13 experimental examples are Linear, Jira, Azure DevOps, Slack, Teams, Confluence, Sentry, ServiceNow, GitLab, PagerDuty, Datadog, Zendesk and Notion. Each cites official sources and includes XML authoring documentation and consumer examples.

Importing selects nothing and grants no provider access. Select bounded REST/GraphQL reads, reviewed hosted MCP methods, safe outputs and protected gateway triggers independently. Only selected phase capabilities, endpoint/resource grants and credential references enter content-addressed runtime snapshots. Provider evidence comes through selected reads, not automatic context hydration.

This configuration excerpt exposes one hosted Jira method without JQL search:

imports:
  - uses: .github/workflows/connectors/jira.md
    with:
      cloud-ids: [00000000-0000-4000-8000-000000000001]
      issues: [APP-1]
tools:
  jira:
    personal: [getJiraIssue]
safe-outputs:
  staged: true
  jira-add-comment:
    max: 1

Replace specimen IDs and provision the named reader credential. Unknown methods, wildcards, duplicates and empty subsets reject; typed arguments, exact grants and phase credentials remain enforced. The service-account profile supports the same subset syntax. Legacy full-profile selections remain available when deliberately needed; fixed local reads keep list syntax.

Providers and practical scenarios

All 13 providers are experimental editable declarations, not built-in integrations or live-readiness certifications. Importing enables nothing: consumers independently select reads, safe outputs and protected triggers. The table describes the narrow golden scenario for each provider; declarations may expose additional explicitly selected capabilities.

Provider / declaration	Read evidence and golden scenario	Selected golden output and important limits
Linear	Issue details plus bounded comments for bug intake triage.	Staged Linear comment. Exact organization/team/issue grants and separate read/write credentials; IDs discovered in lists do not become write grants.
Jira	Exact hosted personal: [getJiraIssue] read for first-response triage; independent bounded REST readers are also declared.	Staged Jira comment, without JQL or provider write tools in the agent. MCP authorization/scopes are distinct from REST access; the observed read still has a missing scope-claim error after API-token authentication was enabled.
Azure DevOps	Actual work-item description for an engineering handoff; bounded repository/PR/text readers are separately selectable.	Staged work-item comment. Exact numeric-string resource grants and endpoint/project checks; hosted MCP and REST require different approved token audiences. Legacy ado-* handlers are not restored.
Slack	Complete short-thread messages for decisions, actions and open questions.	One staged same-thread reply. Replace declaration-owned specimen pins; incomplete/long reads stop instead of generating an acknowledgement or fabricated summary.
Microsoft Teams	Approved channel root-message content for action-item extraction.	Staged GitHub issue. Graph resource-specific consent/installation and a reader token are required; partial reply pages and Graph IDs do not establish Bot Connector authority.
Confluence	Actual storage-format page body/version for deployment and rollback runbook readiness, with two explicit GitHub duplicate-check readers.	Staged GitHub issue. OAuth acquisition/renewal is external; declared provider writes use fixed placeholder text rather than generated findings.
Sentry	Hosted known-issue diagnostic details for an investigation handoff.	Staged GitHub issue, not resolution. Review diagnostic disclosure/OAuth and exact URL/resource pins; REST status metadata alone is not diagnosis.
ServiceNow	Incident number/raw state/revision plus an operator briefing for shift handoff.	Staged internal work note. Instance OAuth scopes and record/field ACLs are administrator-owned; no journal history or invented cause, and a sys_id response does not prove journal persistence.
GitLab	Open/draft merge-request metadata for author/reviewer intake.	Staged MR note. Use the project-local IID and separate reader/writer tokens; metadata is not a diff/code review and independent pipeline grants do not prove association.
PagerDuty	Active incident/service/status/urgency snapshot for responder handoff and suggested checks.	Staged incident note. Full REST authorization header and an approved From identity are needed for separately authorized live delivery; no logs, root cause or lifecycle change is inferred.
Datadog	Alert/Warn monitor metadata for an engineering investigation request.	Staged GitHub issue. OAuth client eligibility is restricted to approved partners and refresh is external; ordinary API/application-key pairs, diagnostic telemetry and monitor/incident correlation are not assumed.
Zendesk	Unresolved-ticket ID/status/subject/update time for support-to-engineering ownership handoff.	Staged private GitHub issue. No conversation/body evidence; provider-note normalization/event-order verification remains restrictive, so the golden avoids that writer.
Notion	Page ID/URL/edit timestamp compared with a UTC cutoff for human reference maintenance.	Staged Notion comment. Share the page with the internal connection; no body/title/owner/comment inspection or cross-run duplicate suppression is implied.

Golden consumer fixtures live under pkg/cli/workflows/<provider>-golden.md; schema-enabled compiler tests and make compile-cli-workflows compile every one in an isolated deployment layout. Each golden selects a small reader surface and one max: 1 staged task effect. Staging suppresses writes and writer credential delivery, not reads. Provider provisioning, consent, refresh, actual visibility, and receiver deployment/enrollment remain external; protected trigger compilation is not working webhook ingress.

Source-only golden workflow fixtures

All 13 common-scenario goldens live beside CLI test workflows at pkg/cli/workflows/<provider>-golden.md, not in the active Actions workflow directory. Their contents were preserved byte-for-byte during relocation; their 13 generated active .lock.yml files were removed. Editable provider declarations remain at their original paths.

The goldens cover issue triage, a work-item engineering handoff, short-thread decisions/actions, approved Teams tasks, runbook readiness, known-error investigation, incident shift handoff, MR intake, responder checks, monitor investigation, private support-to-engineering ownership, and timestamp-based reference maintenance. Each uses manual dispatch, exact specimen grants, a minimal provider read surface, one max: 1 staged task effect, and Bash/edit/CLI proxy disabled. GitHub readers are disabled except for Confluence's two explicit duplicate-check methods. Framework reporting/noop tools are not counted as task effects.

TestConnectorGoldenWorkflows actually compiles every source with schema validation in an isolated .github/workflows deployment layout, preserving import confinement, exact advertisement/reader/credential/effect assertions, exhaustive fixture matching and staged writer omission. make compile-cli-workflows independently compiles all 13 source-only goldens with --validate --strict --no-emit, without relying on companion lock discovery. Setup still discovers the local fixtures offline. Adopting a fixture means copying it into the deployment layout with the reviewed declaration and replacing all specimen bindings; these files do not themselves add active Actions workflows.

The existing examples comment remains pinned to its historical source revision. Current paths, integration evidence and setup limits are documented in the human reference and .github/aw/connectors.md. Metadata-only sources do not become diagnostic/body readers through prompting; some goldens deliberately use a GitHub handoff rather than a placeholder or insufficiently verified provider writer.

Connector safe-output samples

Connector selections accept the existing deterministic MCP replay samples contract: a single argument object or an array of objects, validated against the generated connector tool input schema. For example, with a matching declared operation:

features:
  samples: true
safe-outputs:
  tracker-add-comment:
    max: 1
    staged: true
    samples:
      - issue: ISSUE-1
        text: Example comment

features.samples: true or gh aw compile --use-samples uses the ordinary MCP tools/call replay path instead of the agent. Declaring samples alone does not enable replay or change tool advertisement. Built-ins retain their existing replay order, then connector tools are sorted by name and samples retain authored order. Missing-sample coverage warnings include connector selections.

Replay is not staging or a dry run. Samples are data, not instructions, resource grants or delivery policy. Exact resources, phase credentials, sanitization, threat policy and proposal budgets still apply; excess samples do not increase max. Generated plans/digests, tool schemas, scripts and handler policy are unchanged by sample data. Keep previews staged.

Runtime expression values now travel separately from static replay JSON and are bound only to authored string slots after parsing. Event text cannot create a different tool, argument object or patch sidecar. Schema normalization matches built-in placeholder validation for enums and length limits. Regressions cover invalid shapes/payloads, required fields/types/lengths/enums/patterns, unknown authority/control arguments, feature/flag modes, expression validation, built-in coexistence, credential-free resource denial and real offline stdio MCP replay, including crafted text that previously could inject replay control fields.

Connector-aware repository configuration

gh aw init, gh aw new and gh aw secrets bootstrap discover repository-local declarations, wrappers and importing consumers/goldens offline, without displaying binding values or fetching remote imports. gh aw connector <id> setup shows input types/required/default availability, declared endpoints, phase credentials/scopes, and credentials plus authentication XML metadata, including normal local/cached pinned wrappers. Required bindings use --input name=JSON; Zendesk needs both a subdomain and a string ticket ID. Extracted setup documentation is clearly marked as untrusted and fenced with collision-safe delimiters at the final presentation boundary; this is a trust cue, not a guarantee of immunity to prompt injection.

gh aw edit --add-import / --remove-import accept schema-validated normal uses/with objects. Adding an import does not select tools, network permissions or grants. Setup/discovery do not activate capabilities or ingress. Bootstrap checks engine/system prerequisites only: provider provisioning, consent, refresh, ACLs and authorization remain external.

An integrated CLI regression exercises setup against the actual bindings of all 13 relocated goldens. Init/new nonactivation, import edits, bounds/symlinks, cached pinned metadata and bootstrap messaging remain covered.

Shared execution and authority

The Node runtime ships with actions/setup; no provider-specific checkout, runtime build or CLI installation is required. Go/Node enforce frozen typed plans, bounded transport, exact response/resource evidence, and separate character/byte limits. Selected reads do not create write grants, and independent grants do not prove parent/tenant/tuple membership.

Staging suppresses mutations, writer credentials, preflights and creation receipts, not selected reads or arbitrary authored scripts. Global/compiler staging cannot be disabled by per-operation false. Attempts use private dispatcher budgets (max 1-100, default 1). Optional bounded retries never replay authorization failures, uncertain transport or evidence failures; writes additionally require explicitly repeat-safe idempotent PUT/PATCH/DELETE semantics. POST creates/appends cannot opt in.

Human text uses shared trusted publication sanitizers and protected attribution/footers. Trusted destinations, bounded lookups/checks, authenticated creation receipts, fixed patch additions and content-addressed binary staging remain separate from agent-controlled text and returned URLs. Staged proposals never establish creation or follow-up authority. Node guarded file I/O requires Linux.

Matching connector XML is removed before substitution/prompt assembly; scanner path exemptions remain removed. Automatic legacy context fetching and agent-job context-file writes are removed, while selected reader App/OIDC credential minting remains intact. Legacy context input validation does not deliver context credentials or fetched output. The prompt's untrusted-data instruction now covers every selected connector, including read-only tools without context selection. Runtime URL imports remain rejected; reviewed pinned compile-time imports remain supported. Connector staging artifacts require successful built-in/custom redactors and initial recovery validation; later agent archives additionally require final recovery validation. Failed/skipped/cancelled validators do not permit upload.

Manifest provenance preserves the trusted handler result's connector identity before GitHub fallback, retaining explicit provider precedence without tool-prefix guessing. Staged proposals are not recorded as applied writes.

Protected triggers, separate ingress deployment

Flat on.gateway-dispatch.<id> and qualified root selections lower to the same protected route; the removed connectors wrapper is rejected. Repository opt-in, exclusive gateway routing, exact source grants, declared resource origins, approved App provenance and hash-bound admission are required. The obsolete native jira-issue selection and its stale integration expectations are removed; this does not remove declarative Jira connector triggers.

Seven Linear, seven Jira and eight Azure lifecycle selections use bounded typed source predicates and independent narrowing filters. Frozen predicates enforce 64 nodes, depth six, 100 array/membership values and 6,400 evaluation visits; exhaustion is unknown/nonmatching. UTF-8 ordering and semicolon URL handling are deterministic across Go/Node. Jira's shared native tool schema and Confluence's common page-trigger contract use YAML anchors with explicit event overrides; regression tests verify equivalent frozen plans and distinct event behavior across the import/Go/Node paths.

Compilation emits digest-bound subscriptions and admission gates; it does not deploy receivers, enroll sources, establish replay storage or authenticate actual provider deliveries. No provider dispatch or receiver deployment was performed.

Migration and practical limits

This is a breaking replacement of native Linear/Jira/Azure handlers and automatic credential wiring, not a legacy alias layer. Linear deliberately omits six long-tail reader families rather than adding an arbitrary forwarding proxy; bounded Jira and Azure capabilities retain explicit resource/identity evidence and independently selected methods.

After API-token authentication was enabled, the observed Jira MCP read changed from a policy denial to a tool-level 401 because the session token lacks the required scope claim. Historical REST writes do not establish hosted MCP authorization, and no identity fallback was added. Datadog OAuth eligibility is restricted to approved partner clients; ordinary API/application-key pairs are unsupported. Zendesk live-note normalization/event-order verification remains restrictive, so its golden uses a GitHub handoff. These are narrow experimental building blocks, not live-readiness certifications.

Validation and publication

Latest published branch: 4179c42b36eba5da8cf7ad5b7c102de6751e0bea, with origin/main merged through d5a3bbc9948b931173742de4fbff766e8a021537. All 357 active workflow sources recompiled and all 13 source-only provider goldens compile. Relevant provider/durable-engine Go regressions, JavaScript suites, typecheck and native/WASM builds pass. Publication-gate custom-linter blockers were checked against unchanged main source; no checks were disabled. Earlier validation below is historical evidence for its recorded snapshot, not a claim that all current hosted checks are green.

Published review batch: c48f0edda4840e7334c8706dd3d763364fd361dc, based on 72cb5088a6e with main merged through 4f55248ba0c43e250147c7dc6a0988756a5fee53. Parent reviewed the parallel task results and made the final commit/push once. The ADR draft claimed by automation was absent; the proposed record is now actually published and linked above. No workflow allowlist was relaxed or skipped publication treated as success.

The combined workflow/parser/CLI/connectors regression selector passes, including schema-enabled compilation of all relocated goldens, sample replay and provider authority boundaries. All 355 active workflows compile with zero lock drift; all 13 source-only CLI goldens compile separately. The tagged gateway integration suite passes against the source-built binary. Native/WASM builds, typecheck and 363 targeted JavaScript tests pass (three existing skips). Standard Go lint reports zero issues; schema freshness and JavaScript lint pass.

The final combined no-test gate remains nonzero for 15 custom-linter findings in unchanged existing samples_replay.go/samples_validation.go lines. All 15 map to exact pre-batch source lines in 72cb5088a6e; no checks were disabled. New lint findings introduced during implementation were corrected. Earlier baseline init/edit/bootstrap findings remain outside this batch's scope. Child impacted-test gates and recorded focused parent validation passed; test-unit was not repeatedly rerun.

Earlier PR-caused CI fixes repair stale docs links/glossary, standalone session-parser bundled modules, checked-in agent guidance, lifecycle-context isolation and nested provider aliases without loosening alias safeguards. All four hosted JS shards passed at acd76a6 in run 41586423824. Main's Agy and WASM golden corrections are now merged. Visual gallery setup remains a separate pre-existing issue tracked in #74384. New hosted results for the latest head are not yet established.

Credential/action compilation review

Golden reader references are names only: AZURE_DEVOPS_READ_TOKEN, CONFLUENCE_READ_ACCESS_TOKEN, DATADOG_MONITOR_READ_OAUTH_TOKEN, GITLAB_READ_TOKEN, JIRA_MCP_PERSONAL_BASIC_AUTH, LINEAR_READ_API_KEY, NOTION_READ_TOKEN, PAGERDUTY_READ_AUTHORIZATION, SENTRY_MCP_OAUTH_TOKEN, SERVICENOW_READ_TOKEN, SLACK_READ_TOKEN, TEAMS_GRAPH_READ_ACCESS_TOKEN, ZENDESK_READ_OAUTH_TOKEN.

Each reference was reviewed against its explicitly selected read phase, approved specimen resources and declared provider route; none introduces a writer credential into staged output or an arbitrary credential destination. Golden action references already existed in baseline workflows. This review batch adds no credential references, action repositories/pins or redirect changes; removing automatic legacy context fetches also removes those context credentials from agent-job delivery. No secret values were read or committed. Actual identity permissions, OAuth eligibility, consent, expiry and provider compatibility cannot be established offline and require author/human review before deployment.

Compiler/mock/fixture results are not LLM-output quality evidence or proof of real provider authentication or mutation delivery. No provider credentials were provisioned, provider mutations executed or ingress installed. A separately authorized read-only Jira smoke rerun was performed; its failed authorization does not establish successful provider access.

[pelikhan]

@copilot merge main, fix conflicts.

review ado integration, ensure that the new driver is operational. Compare to old native runner.

[Copilot]

@copilot merge main, fix conflicts.

review ado integration, ensure that the new driver is operational. Compare to old native runner.

Starting the latest-main merge and Azure DevOps (ADO) driver review. I’ll compare its capabilities and runtime behavior with the former native runner, verify any differences against available tests/fixtures, and preserve the existing changes while resolving merge conflicts.

[gh-aw-bot]

@copilot

Copilot assignment requested for the following outstanding work:

1. Update this branch with the latest main using make merge-main, resolving any conflicts and preserving the intended changes.
2. Fix failing check conclusion (FAILURE): https://github.com/github/gh-aw/actions/runs/42404149055/job/128500539332.

Once you start work, post this work summary as a PR comment without the leading Copilot mention, including the Sous-chef head, work, and state lines below, to record that the assignment is running. Apply the necessary fixes on this PR's existing branch, reply to each listed review thread and resolve it when addressed. Ignore feedback already answered or resolved; stop when only human review or CI remains. Do not merge or trigger CI.

Sous-chef requested-head: 3e60567
Sous-chef requested-work: 51e2287c3d1ee41b7e13769862add61dcd292a623cf943abc5968c984e246bcf
Sous-chef requested-state: ea55ea81e67a51dfac22909810440740d00b8f800b91375443700c05c2fa46da

Generated by 👨🍳 PR Sous Chef · pi · haiku45 · ~10 AIC · ⌖ ~14 AIC · ⊞ 1.2K · ◷
_{Comment /souschef to run again}

[Copilot]

@copilot

Copilot assignment requested for the following outstanding work:...

Starting the requested latest-main merge and investigation of the failing conclusion check, alongside the ADO driver review.

Sous-chef requested-head: 3e60567
Sous-chef requested-work: 51e2287c3d1ee41b7e13769862add61dcd292a623cf943abc5968c984e246bcf
Sous-chef requested-state: ea55ea81e67a51dfac22909810440740d00b8f800b91375443700c05c2fa46da

@copilot merge main, fix conflicts.

review ado integration, ensure that the new driver is operational. Compare to old native runner.

Merged latest main and resolved the session_parsers.go embed conflict in 7832fd97. The ADO review found the shared declarative driver exercises create/update/comment/assign/link writes and bounded read paths; attachment handling is now a receipt-bound upload/attach flow. Unlike the native runner, it intentionally drops implicit PAT/SYSTEM_ACCESSTOKEN fallback and broad target authority in favor of phase-scoped credentials and exact grants. Targeted Go tests and all 238 connector-runtime JavaScript tests pass. These are mock-backed checks; live Azure identity, permissions, and receiver deployment remain unverified.

[github-actions]

Visual Regression Check

Page	Viewport	Status
/gh-aw/	Mobile 375×812	error
/gh-aw/	Tablet 768×1024	error
/gh-aw/	Desktop 1440×900	error

The docs server at (host.docker.internal/redacted) returned **403 Forbidden** (proxy error page) from the sandbox browser, so no screenshots or accessibility snapshots could be captured. Some commands were also blocked by workflow tool permissions. Please check the AWF domain allowlist for host.docker.internal:4321`.

Warning

Firewall blocked 2 domains

The following domains were blocked by the firewall during workflow execution:

• host.docker.internal
• update.googleapis.com

To allow these domains, add them to the network.allowed list in your workflow frontmatter:

network:
  allowed:
    - defaults
    - "host.docker.internal"
    - "update.googleapis.com"

See Network Configuration for more information.

Generated by 👁️ Visual Regression Checker for #74077 · copilot · auto (Claude Sonnet 5.5) · ~12 AIC · ⌖ ~1 AIC · ⊞ 8.6K · ◷

[pelikhan]

@copilot merge main, fix conflicts, recompile

[Copilot]

@copilot

Copilot assignment requested for the following outstanding work:...

Starting the requested main merge, conclusion check investigation, and workflow recompilation.

Sous-chef requested-head: 3e60567
Sous-chef requested-work: 51e2287c3d1ee41b7e13769862add61dcd292a623cf943abc5968c984e246bcf
Sous-chef requested-state: ea55ea81e67a51dfac22909810440740d00b8f800b91375443700c05c2fa46da

@copilot merge main, fix conflicts, recompile

Merged latest main and recompiled all 361 workflows successfully in de9d536b; no conflicts remained. The final impacted Go/JavaScript tests passed. The full progress gate still reports existing custom Go linter findings, and the reported conclusion failure was the Visual Regression Checker’s 403 preview-access failure.