# Integrations, integration connections, and tools (https://www.shipfox.io/docs/understand/integrations-connections-and-tools)

Description: See how integration connections carry events and tools without exposing saved credentials.

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 [#what-each-term-means]

| 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.                                           |
| Slug of an integration connection | The name a workflow uses 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                  | An external operation that a tool step or an agent performs through an integration connection. |

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-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-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 [#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](https://www.shipfox.io/docs/reference/workflow-schema#trigger-fields)
defines the exact trigger contract. [Set up work](https://www.shipfox.io/docs/how-to/set-up-work) explains
how to create an integration connection.

## Checkout access is separate from tools [#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 [#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](https://www.shipfox.io/docs/integrations/github/tools) marks each classification and
indirect target.

## The workflow never receives the credential [#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 [#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](https://www.shipfox.io/docs/how-to/author-workflows/call-integration-tool) for a tool step and
[Agent access](https://www.shipfox.io/docs/how-to/author-workflows/use-integration-tools) for an agent
with tools. The reference for [tool step
fields](https://www.shipfox.io/docs/reference/workflow-schema#tool-step-fields) and [agent integration
fields](https://www.shipfox.io/docs/reference/workflow-schema#agent-integration-fields) lists the exact
selection and write fields. [Agents](https://www.shipfox.io/docs/understand/agents) explains how this
access fits with the harness, model, and native tools. [Manage GitHub repository
access](https://www.shipfox.io/docs/how-to/set-up-work/manage-github-repository-access) explains how to
change both repository boundaries.