Integrations, integration connections, and tools
See how integration connections carry events and tools without exposing saved credentials.
An integration is Shipfox support for an external provider. An integration connection links one workspace to a specific account or installation at that provider.
A workspace can connect the same provider more than once. Each integration connection has its own events, reach, and saved credential.
Events bring data in. Tools let an agent act outside the run. Checkout access handles the code. None of these grants another one by itself.
The rule is least access. Name the account, tool, and repository. Add write access only when the task needs it.
This makes review easier. The workflow shows both the account and the allowed action. Access stays clear.
The names describe different layers
These terms have different jobs.
| Term | Meaning |
|---|---|
| Provider | The external service, such as GitHub or Sentry. |
| Integration | How Shipfox works with that provider. |
| Integration connection | One account or installation linked to the workspace. |
| Integration connection slug | The workflow name for that integration connection. |
| Event source | The integration connection that sent an event. |
| Project source | The integration connection and repository used for workflow files and checkout. |
| Native agent tool | A harness action inside the runner, such as reading or editing files. |
| Integration tool | A selected external action performed through an integration connection. |
These layers answer separate questions. The provider says which system is involved. The integration connection says which account. The project source says which repository owns the work. A tool says which operation the agent may perform.
Integration connections can receive events or expose tools
An integration connection can play one or both roles.
- Event source: the external system delivers facts that triggers or listening jobs can match.
- Tool provider: an agent receives selected operations for reading or changing data in that system.
Receiving an event grants no tool. Selecting a read tool grants no write tool. The workflow makes each choice separately.
This separation lets an event start low-authority work. For example, a Sentry issue can start an agent that reads only the project checkout. A later, checked step can receive a narrow GitHub operation to open a pull request.
A slug selects the workspace integration connection
Triggers and agent tools use the integration connection slug. It names one workspace integration connection, not only a type of provider.
Two GitHub integration connections may emit the same event name. Their slugs keep those events separate. The same rule prevents an agent tool from silently switching to another account.
The exact trigger contract lives in the workflow schema reference. Integration connection setup belongs in Set up work.
Project checkout is a separate path
A project chooses one source integration connection and repository. Shipfox uses that binding to discover workflow files and to prepare job checkouts.
Checkout permission controls authenticated Git reads or writes for the whole job. It does not grant issue, pull-request, monitoring, or ticket operations.
Integration tools cover those external operations. They do not change the checkout credential. An agent may therefore have this mix.
- A local checkout it can edit but not push.
- A read-only pull-request tool but no issue tool.
- A write tool for one operation and one repository.
Keeping these paths separate avoids treating "GitHub access" as one broad permission.
Credentials stay behind the integration connection
The workflow names an integration connection and selected operations. It does not receive the saved provider credential. The agent receives a tool interface, and Shipfox performs authorized calls behind that boundary.
This design narrows both disclosure and use.
- The prompt cannot print a credential it never receives.
- The tool accepts only its defined input shape.
- Repository scope limits where the operation can act.
- Read and write sensitivity remain explicit in the workflow.
The boundary does not make every tool call safe. An agent can still choose a bad value or act on misleading event data. Use the smallest tool selection, place writes after checks, and read back important external results.
Authority should follow the task
Start from no integration tool. Add a read operation when the agent needs external context. Add a write operation only when the workflow intends an external change.
Repository scope should be as narrow as the work. A project-source default is safer than broad account access when the task concerns one repository.
There is a tradeoff between raw flexibility and reviewable authority. A general credential can support many operations but hides the true reach of the step. A small tool selection makes that reach visible in the workflow and during sync.
Use Agent access for the authoring task. The Agent integration fields reference lists exact selection and write fields. Agents explains how this authority fits with the harness, model, and native tools.