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

# Connect GitHub to Your Aven Stream for Delivery Verification

> Link a GitHub repository to your Aven stream so the CLI can verify branch commits and enable final delivery sessions with on-chain code delivery proof.

When you connect a GitHub repository to your Aven stream, you give the `aven-stellar` CLI the ability to verify exactly which code was delivered. The head commit hash of each delivery branch is folded into the evidence hash stored on-chain, creating a tamper-proof link between the payment record and the actual repository state at the moment of delivery.

## Why Connect GitHub

Linking a GitHub repository to your stream unlocks final delivery sessions and strengthens the integrity of every work report you submit.

* **Enables final delivery sessions** — Running `aven stop --ended` requires a connected repository. The CLI uses the connection to verify your nominated delivery branches before constructing the final evidence hash.
* **CLI verifies branch head commits against the remote** — When you nominate a branch, Aven fetches its current head commit from GitHub. You cannot submit a delivery claim for a branch that does not exist on the remote.
* **Evidence hash commits to the exact delivered code** — The head commit hash for each verified branch is included in the evidence hash that is stored on-chain. The hash changes if the branch state changes.
* **Employers can verify the repository content matches the report** — Anyone holding the attestation ID can read the evidence hash on-chain and compare it against the nominated branches at the same commit.

> [!NOTE]
>
> **Requirements before you begin:**
>
> * A GitHub account
> * A repository for the project
> * An active Aven stream
> * You must be the **recipient** of the stream to connect a repository — senders cannot initiate the connection on behalf of a worker

## Steps to Connect

**1. Open your stream page**

Navigate to your stream at `/stream/[id]` on the Aven dashboard. You can find your streams under `/dashboard` in the **Received** tab.

**2. Find the GitHub repository section**

Scroll to the **GitHub Repository** section on the stream page. This section is visible only to the stream's recipient.

**3. Click Connect GitHub**

Click the **Connect GitHub** button. Aven redirects you to GitHub to authorize the Aven GitHub App on your account.

**4. Authorize the Aven GitHub App**

Review the requested permissions in your browser and click **Authorize**. Aven requests `read:user` scope only — it reads your GitHub identity to link your wallet address to your GitHub account. It does not request write access to your repositories.

**5. Select the repository for this stream**

After authorization, select the repository where your project work lives. This is the repository the CLI will reference when verifying delivery branches.

**6. Connection confirmed**

The repository is now linked to the stream. The CLI will use this connection automatically the next time you run `aven stop --ended`. No further setup is needed.

> [!NOTE]
>
> You only need to connect GitHub once per stream. The connection persists until you explicitly disconnect it from the stream page.

## How Verification Works

When you run `aven stop --ended`, the CLI begins a final delivery session. Here is what happens step by step:

1. The CLI prompts you for one or more delivery branch names (for example, `main` or `feature/payment-flow`).
2. It sends those branch names to the Aven dashboard along with the stream ID.
3. The dashboard calls the GitHub API to confirm each branch exists on the remote and retrieves its current head commit hash.
4. The commit hashes are incorporated into the evidence hash alongside the session timing and change statistics.
5. The dashboard calls `verify_work` on the Stream Contract, which stores the evidence hash on-chain and reserves the remaining escrow.
6. The CLI confirms the final session was submitted successfully. Final release still requires explicit client approval in the web application.

```mermaid theme={null}
sequenceDiagram
  participant CLI as aven-stellar CLI
  participant Dashboard as Aven Dashboard
  participant GitHub as GitHub API
  participant Contract as Stream Contract

  CLI->>Dashboard: stop --ended (branch names)
  Dashboard->>GitHub: verify branch head commits
  GitHub-->>Dashboard: commit hashes
  Dashboard->>Contract: verify_work (evidence_hash)
  Contract-->>Dashboard: reservation confirmed
  Dashboard-->>CLI: final session submitted
```

> [!WARNING]
>
> If you push new commits to the delivery branch after the final session is submitted, the evidence hash in the report will no longer match the current branch state. Submit your final session only after all work is complete and pushed to the remote.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.