Skip to main content
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.
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.
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.
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.