# Deploying from a GitHub Repository

Treza Enclaves support deploying directly from a GitHub repository. When you connect a repo, Treza automatically builds a Docker image from your code, pushes it to a private Amazon ECR repository, and deploys it into your enclave — no Dockerfile hosting or manual image management required.

***

### How It Works

```
Your GitHub Repo
      │
      ▼
  Treza Platform
  (OAuth connection)
      │
      ▼
  AWS CodeBuild
  (clones repo, runs docker build)
      │
      ▼
  Amazon ECR
  (private image registry)
      │
      ▼
  Treza Enclave
  (image deployed into isolated enclave)
```

#### Step-by-step

1. **Connect your GitHub account** — Treza uses OAuth to request read access to your repositories. No write access is ever requested.
2. **Select a repository and branch** — Choose any repo and branch you want to deploy from.
3. **Configure your enclave** — Set the enclave name, provider region, and any other settings. No Docker image URI is required.
4. **Treza triggers a build** — AWS CodeBuild clones your repository at the selected branch, builds a Docker image using the `Dockerfile` at the root of your project, and pushes the resulting image to a dedicated ECR repository.
5. **Image is deployed into the enclave** — Once the build completes successfully, the enclave moves from `BUILDING` → `PENDING_DEPLOY` → `DEPLOYED`.

***

### Prerequisites

#### Your repository must contain a `Dockerfile`

Treza's build pipeline runs `docker build` at the root of your repository. Make sure a valid `Dockerfile` exists at the top level of the branch you select.

```
my-repo/
├── Dockerfile        ← required
├── src/
│   └── ...
└── package.json
```

If your `Dockerfile` lives in a subdirectory, you can specify the build context by updating your enclave configuration — see Advanced Build Options.

***

### Enclave Build Statuses

| Status           | Description                                                  |
| ---------------- | ------------------------------------------------------------ |
| `PENDING_BUILD`  | Build has been requested and is queued                       |
| `BUILDING`       | CodeBuild is actively cloning and building your image        |
| `BUILD_FAILED`   | The build encountered an error — check the **Build** log tab |
| `PENDING_DEPLOY` | Build succeeded; enclave deployment is being provisioned     |
| `DEPLOYED`       | Enclave is live and running your image                       |

***

### Monitoring the Build

You can watch live build output directly in the Treza platform:

1. Open the enclave detail page from your **Enclaves** dashboard.
2. Click the **Build** tab in the **Logs** section.

Build logs are streamed from AWS CloudWatch in real time and are sorted chronologically (oldest first), so you can follow the progress from clone → build → push.

***

### Using the CLI

You can also create a GitHub-sourced enclave from the terminal:

```bash
treza enclave create \
  --name my-enclave \
  --provider aws-nitro \
  --source-type github \
  --github-repo my-org/my-repo \
  --github-branch main \
  --github-token ghp_yourPersonalAccessToken
```

The `--github-token` flag accepts a GitHub Personal Access Token (classic) with `repo` scope. This token is used only during the build phase and is stored securely in AWS Secrets Manager for the duration of the build before being deleted.

For interactive prompts, omit the flags and the CLI will guide you through each step:

```bash
treza enclave create
```

***

### Security

* **OAuth tokens** are never stored long-term. The GitHub access token is passed directly to the build environment and deleted from Secrets Manager immediately after the build completes.
* **ECR images** are stored in a private repository scoped to your Treza account. Images are not publicly accessible.
* **CodeBuild** runs in an isolated build environment with no persistent state between builds.
* **Enclaves** run inside hardware-isolated environments (AWS Nitro Enclaves) with cryptographic attestation. The image digest is locked at deployment time.

***

### Advanced Build Options

> Coming soon: support for custom Dockerfile paths, build arguments, and multi-stage build configurations.

***

### Troubleshooting

#### Build failed: `no such file or directory: Dockerfile`

Your repository does not have a `Dockerfile` at the root. Add one to the branch you selected and re-trigger the build from the enclave detail page.

#### Build failed: permission denied cloning repository

If your repository is private, ensure the GitHub account connected to Treza has read access to the repository. For organization repositories, you may also need to approve the Treza OAuth app in your GitHub organization's settings under **Settings → Third-party Access**.

#### Enclave stuck in `BUILDING`

Check the **Build** log tab for errors. If the log tab shows no output after several minutes, the build may have timed out. The default build timeout is 30 minutes. Contact <support@treza.xyz> if the issue persists.

***

### Related

* Deploying a Container Registry Image
* Deploying a Private Registry Image
* Enclave Lifecycle
* Enclave Logs