Connector Specification | GitHub Agentic Workflows
Skip to main content Connector Specification Version : 1.1.1 Status : Experimental Working Draft Publication Date : 2026-11-18 Editor : GitHub Agentic Workflows Team Abstract Section titled “Abstract” This specification defines declaration-only third-party connectors for GitHub Agentic Workflows: explicit capability selection, phase-separated credentials, typed fixed requests, bounded response evidence, staged effects, and protected event subscriptions.
It specifies compiler and trusted-host obligations, offline compliance evidence, and an informative bounded TLA+ model of selected authority boundaries. Status of This Document Section titled “Status of This Document” This Experimental Working Draft is maintained by the GitHub Agentic Workflows project through repository review. It is not a W3C Recommendation or evidence of provider certification. Version 1.1.1 clarifies existing requirements and adds identifiable compliance checks and informative formal models; it does not add runtime capabilities or change accepted declarations.
Publication does not establish provider authorization or operational trigger ingress. Table of Contents Section titled “Table of Contents” Scope and conformance Public authoring and imports Explicit selection and phase pruning Authentication and authority Typed operations and fixed requests Response evidence and bounds Safe-output execution Triggers and context boundary Minimal declaration and consumer Author documentation and conformance evidence Implementation references References Appendices Change Log 1.
Scope and conformance Section titled “1. Scope and conformance” This specification defines the declaration-only connector interface implemented by the gh-aw compiler and shared Go/Node runtimes. It covers imported provider definitions, explicitly selected reads, safe outputs, and protected event subscriptions. It does not define a provider catalog, token acquisition service, webhook receiver deployment, or arbitrary API/script execution interface.
The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “NOT RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119 . Following RFC 8174 , these meanings apply only when the words appear in all capitals. A conforming declaration satisfies both the workflow JSON Schema and semantic connector validation.
A conforming compiler freezes the selected contract without resolving credential values. A conforming execution host enforces phase, resource, endpoint, input, and response constraints. The connector reference describes the supplied provider examples and their limitations. The connector creation skill provides an authoring procedure. Those examples are not live-readiness certifications. 1.1 Conformance classes and document conventions Section titled “1.1 Conformance classes and document conventions” Conformance claims MUST identify their class: declaration , compiler , or execution host .
A declaration conforms to the authoring constraints for its declared capabilities. A compiler conforms to validation, selection, freezing, and distribution requirements. An execution host conforms to the authorization, transport, evidence, and publication requirements for the capabilities it executes, including the trusted outer host’s network and write authorization controls. An embedded transport alone is not that entire host.
Each class MUST satisfy all applicable mandatory requirements; absence of an optional capability does not constitute partial conformance. This document defines no reduced-security conformance levels. A claim MUST identify the specification version, supported capability kinds, tested implementation revision, test results, and any untested or inapplicable capabilities. Sections 1–8 and 10 define requirements. Section 9 is an informative synthetic example, section 11 is an informative implementation index, section 12 classifies references, and sections 13–14 are informative.
Example code and formal models do not override normative prose. A grant is an exact authored resource allowlist; a phase plan is the selected frozen contract delivered to one execution phase; a staged intent is validated proposed work, not delivery evidence or an authenticated resource receipt. 2. Public authoring and imports Section titled “2. Public authoring and imports” A connector is an ordinary Markdown file with YAML frontmatter, conventionally .github/workflows/connectors/<id>.md .
Its declaration is under connectors.<id> . Connector IDs and capability names MUST match ^[a-z][a-z0-9-]{0,62}$ . A connector MUST declare at least one capability. Consumers use normal imports entries with uses and optional typed with bindings. Local imports follow the compiler’s .github/ confinement rules. Remote imports use owner/repo/path@ref ; deployments SHOULD pin a reviewed commit. Imported declarations MUST NOT be silently replaced by built-in definitions, remote fallbacks, or a provider inferred from its name.
Duplicate definitions and generated tool/configuration name collisions MUST fail rather than overwrite another capability. import-schema is the ordinary workflow import-binding schema, not the operation argument schema. It MAY provide resource arrays, reviewed endpoint settings, secret names, and typed defaults. Binding values MUST NOT contain credential values. Empty resource collections do not grant access; a selected capability that needs them MUST fail until it has a valid exact grant.
Constraints on runtime arguments belong in the operation’s inputs even when the same value is an import input. 2.1 Declaration fields Section titled “2.1 Declaration fields” Field under connectors.<id> Contract experimental Boolean; defaults to false . Selecting an experimental connector emits a stability warning, not permission to weaken controls. docs Optional array of unique literal HTTPS documentation URLs without credentials or expressions.
Provenance only; MUST NOT be fetched automatically or grant network access. endpoints Nonempty map of named HTTPS origins without credentials, query, fragment, or a non-root path. credentials Named authentication contracts and references, described in section 4. resources Named arrays of exact approved string IDs or other explicitly constrained identifiers. No wildcard authority. tools Named REST/fixed-GraphQL reader operations, each with an exact exposed tool name. mcp-servers Named streamable-HTTP registrations with exact native tool contracts. safe-outputs Named typed mutation operations executed only by a separately authorized safe-output host. triggers Named native-event evidence and normalization contracts, described in section 8.
Unknown declaration fields MUST fail. There is no public connector context configuration. Content is obtained through selected readers; the compiler MUST NOT hydrate event references or run automatic context fetches. For authoring consistency, declarations SHOULD order fields as experimental , docs , endpoints , credentials , resources , triggers , tools , mcp-servers , and safe-outputs . Primitive inputs SHOULD put type and required before bounds, enum , pattern , and sanitize .
Import bindings SHOULD include concise descriptions and explicit array item types. These are source-format conventions, not semantic map-order requirements. Authors MAY reuse provider-local anchors for identical primitive schemas but MUST preserve scalar quoting, alias dependencies, array order, and independent resource, credential, and response-evidence contracts. Merge keys SHOULD precede explicit overrides for compiler compatibility.
Additional nesting in already-aliased containers requires actual Go/Node conformance evidence, not only a structural YAML parse. 2.2 Internal versioned documents Section titled “2.2 Internal versioned documents” The compiler lowers a declaration into froze
The rest of this page is on the live site.