# Integrations

## What this is

This section explains how Hookshot connections work and how to reason about integration setup.

## When to use it

Use this section when you are connecting an app for the first time or repairing one that is no longer ready.

## What you need first

* Permission to manage integrations in your workspace
* Access to the external app you want to connect

## Steps

### 1. Understand the two kinds of access

* **Trigger Access**: what can start a Protege
* **Tool Access**: what a Protege can do after it starts

Some integrations support both. Others may be used primarily as a source, destination, or chat surface.

### 2. Review the integration lifecycle

1. Open the integration
2. Choose the right connection scope
3. Review Trigger Access
4. Review Tool Access
5. Repair or reconnect anything marked degraded
6. Verify the setup with a real event or schedule

### 3. Choose the right connection scope

Use the smallest connection scope that supports the workflow.

* **Team connections** are shared by the team and fit most production Proteges.
* **Personal connections** are tied to one user and should be used only when the workflow needs that user's account context.
* **Chat connections** are managed at the team level for supported chat surfaces.

### 4. Use a consistent verification loop

For every integration:

* Confirm the connection is active
* Confirm the right trigger source is live
* Confirm the right tools are available
* Confirm chat configuration is complete if the integration receives chat activity
* Confirm Event Feed receives the event
* Confirm Audit shows the run

{% hint style="info" %}
**Engineer note:** The safest way to verify an integration is end-to-end. A healthy connection screen alone does not prove that the event path and action path are both working.
{% endhint %}

## How to verify

You are ready to move on when you can answer:

* What will start this Protege?
* What will this Protege do with the integration?
* Which connection scope owns the workflow?
* Where will I verify that behavior?

## Common failures

* Approving the connection but not checking trigger scope
* Using the wrong connected account or workspace
* Assuming one integration connection covers every team or project boundary
* Repairing Tool Access but forgetting Trigger Access, or the reverse

## Next step

* [Slack](/integrations/slack.md)
* [GitHub](/integrations/github.md)
* [Linear](/integrations/linear.md)
* [Asana](/integrations/asana.md)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.tryprotege.com/integrations.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.