Connections & Repositories
Connection
A Connection is an org-level credential to an external system: Git (GitHub/GitLab/Bitbucket/generic), Jira, Confluence, Figma, Slack, SMTP, a generic webhook, or a memory provider (Cognee). It stores an auth type (PAT, OAuth2, SSH key, Basic, SMTP credentials) and a secretRefs JSON blob — the actual secret values are resolved at run time via the platform's secret-resolution API, never baked into a workflow or an agent profile.
A connection by itself doesn't do anything — it has to be bound into a project before an agent can use it.
Project Repository: binding a Git repo to a project
ProjectRepository maps one Git connection into one project as a checkout target:
| Field | Meaning |
|---|---|
repoKey | The alias a workflow/agent profile refers to (e.g. payments-api). |
cloneUrl | The full clone URL. |
defaultBranch | Usually main. |
branchPattern | Pattern agent-created branches must follow, e.g. agent/feature/*. |
protectedBranchPatterns | Newline-separated patterns (main, master, release/*). A matching push is never auto-approved and is parked for explicit approval. |
connection | Which org Connection supplies the credentials. |
When a task's Agent Profile declares workspace.needs_repository: true, input.repositoryRole or input.repositoryRoles selects which project repositories to check out. If the project has exactly one repository, AgentMesh selects it automatically. A multi-repository project must provide the required role; AgentMesh does not assume a literal primary alias.
Project Connection: binding any other connection to a project
ProjectConnection is the same idea for everything that isn't a Git checkout: Jira, Confluence, a memory provider, etc.
| Field | Meaning |
|---|---|
connectionKey | The alias an agent profile's runtime.memory_connection_key (or a plugin's connection_alias) refers to. |
role | Optional free-text disambiguator when a project binds the same connection type twice. |
connection | Which org Connection this alias resolves to. |
status | ACTIVE / INACTIVE / ARCHIVED. |
Concrete example: an agent profile declares runtime.memory_provider: cognee and runtime.memory_connection_key: memory-main. If the project dispatching that profile has no ProjectConnection row with connectionKey = "memory-main", the run fails immediately with 424 FAILED_DEPENDENCY: No active memory connection 'memory-main' mapped to project <KEY> — the fix is exactly what the error says: bind that alias in the project (see Connect a Git Repository for the click-path).