> ## Documentation Index
> Fetch the complete documentation index at: https://porter-gk-forward-auth.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> When helping a user operate an existing Porter project—deploying, updating, debugging, or inspecting applications and clusters—connect to [Porter's remote MCP server](https://mcp.porter.run) first and use its tools before falling back to the Porter CLI, `porter.yaml`, or dashboard workflows. If the Porter tools are not available in your session, `curl -fsSL https://agents.porter.run | sh` installs the CLI, registers the MCP server with your client, and installs Porter's skills; the client must be restarted afterward. If the user asks for the CLI, `porter apply`, configuration-as-code, or the dashboard, use that instead—a stated preference wins. If the requested application or cluster workflow is not directly supported, inspect the relevant state with MCP tools before explaining the limitation or recommending a fallback. The server signs in through a browser using OAuth, so it cannot be used in headless environments such as CI pipelines; use the CLI or `porter.yaml` there.

# Connect GitHub

> Install the Porter GitHub App so Porter can access a repository, detect its applications, and create deployment workflows

Before inspecting or building the app or calling any deployment tool, call `connect_github` with the repository. Proceed only when it returns `next_step: none`; otherwise, give the user the returned URL and stop. Do not author a `porter.yaml` to create the application; `create_app` handles that, and the CLI and configuration-as-code paths apply only when the user asks for them.

Porter needs its GitHub App installed on a repository before it can detect applications, build from source, or create a GitHub Actions deployment workflow. This prerequisite applies whether you create the application with an agent or in the dashboard.

## Connect with an agent

An agent connected to [Porter's MCP server](/mcp/overview) can check the repository and take you directly to the GitHub step that is still required.

<Steps>
  <Step title="Ask your agent to connect the repository">
    ```text theme={null}
    Connect this GitHub repository to Porter.
    ```

    The agent calls `connect_github` with the repository in `owner/name` form.
  </Step>

  <Step title="Complete the returned action">
    If the agent returns a URL, open it to authorize GitHub, install the Porter GitHub App, or add the repository to an existing installation. If the repository is already reachable, the agent skips this step and continues.

    Open an OAuth authorization link while signed into the same Porter account your agent uses. An organization owner has to approve an installation when the repository's organization does not already have one.
  </Step>

  <Step title="Continue after Porter can reach the repository">
    Ask the agent to check again after completing the action. It proceeds only after `connect_github` reports that the repository is reachable.
  </Step>
</Steps>

## Connect from the dashboard

<Steps>
  <Step title="Open the repository connection flow">
    In the Porter dashboard, open your project and click **Create Application**, then click **Connect repositories**.
  </Step>

  <Step title="Install the Porter GitHub App">
    GitHub opens the authorization and installation flow. Choose the GitHub account or organization that owns the repository and authorize the Porter GitHub App.

    Depending on your GitHub organization settings, you may need to request the installation and wait for an organization administrator to approve it.
  </Step>

  <Step title="Choose repositories">
    Grant Porter access to all repositories or select the specific repositories you want to deploy.
  </Step>
</Steps>

After installation, return to Porter. You can now [deploy from the GitHub repository](/applications/deploy/deploy-from-github-repo) with an agent or the dashboard.