# Connect your product (/docs/guides/connect-product)



Connect a GitHub repository when the product definition lives with the code. You can also use an MCP endpoint, an OpenAPI URL, or a local contract file.

<Callout type="warning" title="Use a safe test environment">
  Connect a sandbox or staging environment for actions that can change data.
  Production connections remain read-only until Invokeable can verify a safe
  testing boundary.
</Callout>

## Add the connection [#add-the-connection]

<Steps>
  <Step>
    ### Open Catalog [#open-catalog]

    Select **Catalog** in the sidebar. If the workspace has no connection, use the empty-state action. Otherwise open **Connection settings**.
  </Step>

  <Step>
    ### Enter the product details [#enter-the-product-details]

    Choose **GitHub** and enter `owner/repository`. Invokeable looks for one `invokeable.yaml` or `invokeable.yml`. If neither exists, it looks for one conventional OpenAPI file. Use **Source path** when the repository contains several products or contracts.

    Choose **URL** to connect an MCP or OpenAPI endpoint directly. Choose **File** to import OpenAPI JSON or YAML, or an MCP tools JSON file.

    <DocImage src="/images/product/connect-product.jpg" alt="Connect your product form with GitHub, URL, and file connection choices" caption="Keep the product definition with the code, or connect a live endpoint directly." />
  </Step>

  <Step>
    ### Describe the environment accurately [#describe-the-environment-accurately]

    Use the environment classification shown during setup. A sandbox or staging connection may allow approved write actions. Production starts conservatively.
  </Step>

  <Step>
    ### Add a credential if requested [#add-a-credential-if-requested]

    Paste the token or API key into the secure credential form. The browser encrypts it with the active public key and binds the encrypted value to this workspace, request, and connector.
  </Step>

  <Step>
    ### Review discovered actions [#review-discovered-actions]

    When discovery finishes, open the Catalog and check every action that can change state. Confirm its permissions, confirmation behavior, retry behavior, recovery path, and verification method.

    Invokeable leaves out operations whose executable fields may contain credentials. The connection shows how many were left out. If every operation has credential fields, Invokeable stops without creating an executable catalog.
  </Step>
</Steps>

## Add invokeable.yaml [#add-invokeableyaml]

Place the file at the repository root for one product. In a monorepo, place one beside each product and provide its path when you connect the repository.

```yaml title="invokeable.yaml"
version: 1
product:
  name: Commerce API
  description: Customer order and payment operations.
source:
  type: openapi
  path: openapi.yaml
environment:
  name: Staging
  url: https://staging-api.example.com
authentication:
  scheme: bearer
  name: Staging API token
```

For MCP, use a live endpoint instead of an OpenAPI path:

```yaml title="invokeable.yaml"
version: 1
product:
  name: Commerce tools
source:
  type: mcp
  endpoint: https://staging-tools.example.com/mcp
environment:
  name: Staging
  url: https://staging-tools.example.com
```

Do not put tokens, API keys, or credentials in this file. Invokeable asks for them separately and encrypts them before storage.

## Import a contract file [#import-a-contract-file]

Choose **File** when the endpoint is not directly reachable or you want to review an exported definition. OpenAPI files can use JSON or YAML. MCP tool exports use JSON. Importing a file adds action definitions, but it does not prove that Invokeable can call or verify the live product.

## Refresh a connection [#refresh-a-connection]

Use **Refresh catalog** after the endpoint definition changes. Review added, changed, and removed actions before running affected journeys. A refresh failure leaves the last approved catalog available for historical context but may block current runs.

## Credential safety [#credential-safety]

* Use the narrowest credential that can complete the selected journeys.
* Do not paste a secret into a journey description, support message, or evidence field.
* Rotate a credential from the source system, then update the connection.
* Remove or archive a connection that should no longer be used.

## If discovery fails [#if-discovery-fails]

For GitHub, confirm that the app can read the repository and branch. If Invokeable finds several manifests or OpenAPI files, provide **Source path**. For URL connections, check network reachability, the document format, and required authentication.

See [Review the Catalog](/docs/guides/review-catalog) and [Troubleshooting](/docs/reference/troubleshooting).