Integrations, integration connections, and tools

An integration is Shipfox support for an external provider, such as GitHub or Sentry. An integration connection links one workspace to one account or installation at that provider.

A workspace can connect the same provider more than once. Each integration connection has its own events, its own reach, and its own saved credential.

An integration connection can bring events in, give a workflow tools to act outside the run, and provide checkout access to code. None of these grants another one by itself. Name the account, the tool, and the repository, and add write access only when the task needs it. The workflow then shows both the account and the allowed action.

What each term means

Each term answers a different question. The provider is the external system. The integration connection is the account. The project source is the repository that owns the work. A tool is one operation that a step can perform.

An integration connection can receive events, provide tools, or both

An integration connection can play one or both roles.

• Event source: the provider delivers events that triggers or listening jobs can match.
• Tool provider: a tool step calls one operation, or an agent receives selected operations, to read or change data in that system.

An event grants no tool. A read tool grants no write tool. The workflow makes each choice separately.

This separation means an event can start work that has little authority. For example, a Sentry issue can start an agent that reads only the project checkout. A later, checked step can then receive one narrow GitHub operation to open a pull request.

A tool step and an agent step use the same tools

A tool step names one tool and its inputs in the workflow. Shipfox makes the call on its API and stores the response as step outputs. No model chooses the call, so the same run data always produces the same call.

An agent step receives a selection of tools. The agent decides when to call them and with which values. That freedom fits work that needs judgment. It costs a model turn and makes the exact calls less predictable.

Both paths use the same tool catalog, the same integration connection checks, and the same audit record. Use a tool step when the workflow already knows the operation and its values. Use an agent step with tools when the agent must decide.

The two paths treat writes differently. An agent step must set allow_write to receive a write tool, because the model chooses the calls. A tool step needs no flag, because naming the write tool is the choice. The run view marks the step as a write either way.

A slug names one integration connection

Triggers, tool steps, and agent tools use the slug of an integration connection. The slug names one integration connection in the workspace, not a kind of provider.

Two GitHub integration connections can send the same event name. Their slugs keep those events apart. The same rule stops a tool from switching to another account without notice.

The workflow schema reference defines the exact trigger contract. Set up work explains how to create an integration connection.

Checkout access is separate from tools

A project chooses one source integration connection and one repository. Shipfox uses that choice to find workflow files and to prepare job checkouts.

Checkout permission controls authenticated Git reads and writes for the whole job. It doesn't grant issue, pull request, monitoring, or ticket operations.

Integration tools cover those external operations. They don't change the checkout credential. An agent can therefore have this mix:

• A local checkout that 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.

These separate paths mean that "GitHub access" is never one broad permission.

Repository access adds two boundaries

The provider sets the outer repository boundary. For GitHub, this is the repository selection on the GitHub App installation.

Shipfox can add a direct-target guardrail inside that boundary. In selected mode, explicit checkouts and direct tool targets must match repositories used by Shipfox projects. In all mode, Shipfox skips that project check.

This guardrail does not resolve opaque IDs or every indirect provider effect. The provider installation remains the boundary for those operations. The GitHub tool catalog marks each classification and indirect target.

The workflow never receives the credential

The workflow names an integration connection and the selected operations. It doesn't receive the saved provider credential. A tool step or an agent gets a tool interface, and Shipfox makes the authorized calls behind it.

This limits both disclosure and use.

• The prompt can't 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 access stay explicit in the workflow.

The boundary doesn't make every tool call safe. A tool step can carry a bad value from the event, and an agent can act on misleading event data. Use the smallest tool selection, put writes after checks, and read back important external results.

Give each step only the access it needs

Start with no integration tool. Add a read operation when a step needs external context. Add a write operation only when the workflow intends an external change. Prefer a tool step for a write with known values, so the workflow states the exact call.

Keep the repository boundary as narrow as the work. For GitHub, use selected mode and a narrow App installation when the task concerns one repository.

A general credential supports many operations but hides the real reach of the step. A small tool selection makes that reach visible in the workflow and at sync time.

Use Call an integration tool for a tool step and Agent access for an agent with tools. The reference for tool step fields and agent integration fields lists the exact selection and write fields. Agents explains how this access fits with the harness, model, and native tools. Manage GitHub repository access explains how to change both repository boundaries.