# Contribute To Codra

> Learn how to contribute to Codra with the recommended GitHub workflow, TypeScript conventions, CLA requirement, and private security reporting policy.

Canonical: https://codra.run/docs/contributing
Last updated: 2026-11-01

<GitBranch size={24} strokeWidth={1.75} />
    <p className="text-base font-medium text-foreground">Open Workflow</p>
    <p className="text-sm text-foreground/70">Fork, branch, PR. Contributions are welcome from anyone.</p>
  
  
    <Code2 size={24} strokeWidth={1.75} />
    <p className="text-base font-medium text-foreground">TypeScript First</p>
    <p className="text-sm text-foreground/70">Full type coverage. Zod for runtime validation boundaries.</p>
  
  
    <ShieldCheck size={24} strokeWidth={1.75} />
    <p className="text-base font-medium text-foreground">CLA Required</p>
    <p className="text-sm text-foreground/70">Sign the contributor license agreement before your first PR is merged.</p>
  

<h2 id="workflow">Workflow</h2>

Contributions are welcome. The recommended workflow keeps changes focused and easy to review.

1. **Fork the repository** — Fork <a href="https://github.com/devarshishimpi/codra" target="_blank" rel="noopener noreferrer" className="text-primary hover:underline">github.com/devarshishimpi/codra</a> and clone your fork locally.
2. **Create a focused branch from main** — Name your branch descriptively — fix/webhook-signature or feat/model-config-ui, for example.
3. **Install dependencies** — `npm install` and copy `.dev.vars.example` to `.dev.vars` with your secrets filled in.
4. **Make your change** — Keep the scope tight. Prefer existing patterns over new abstractions.
5. **Run typecheck and tests** — `npm run typecheck` and `npm test` must both pass before opening a PR.
6. **Open a pull request** — Open your PR against `main`. Write a clear description of what changed and why, and reference any related issues.

> **INFO:** 
> Pull requests are reviewed and merged directly into <code>main</code>; there is no separate <code>dev</code> integration branch. Run <code>npm run typecheck</code> and <code>npm test</code> before opening a PR, and ensure the required CI checks pass.

<h2 id="conventions">Engineering Conventions</h2>

| Topic | Guideline |
| --- | --- |
| Scope | Keep changes focused and intentional. One logical change per PR. |
| Abstractions | Prefer existing patterns over new abstractions. Read adjacent code before introducing new helpers. |
| TypeScript | Full type coverage required. Use Zod schemas for runtime data boundaries, especially for external API responses. |
| Dashboard UI | Keep dashboard pages clear, dense, and operational. Avoid decorative complexity that reduces information density. |
| Secrets | Do not commit secrets, .dev.vars files, or generated deployment credentials under any circumstances. |
| Tests | Add or update tests when behavior changes. The suite lives under test/ and uses Vitest. |
| Migrations | Database schema changes require a new migration file in db/migrations/ following the existing naming convention. |
| Documentation | Docs live in `docs/*.mdx`. Use `<h2 id="...">` for headings, `<Note>` for callouts, and keep `docs/docs-seo.ts` updated. |

<h2 id="docs-contributions">Contributing to Documentation</h2>

All documentation content for [codra.run/docs](https://codra.run/docs) is stored in the public `docs/` folder in the Codra repository.

Even though the frontend hosting is managed separately in a private repo, documentation content is 100% open source. When changes are merged into `main`, an automated GitHub Actions workflow copies the updated MDX files and deploys them to the website.

### Guidelines for Docs
* **Files & Routing**: Stored in `docs/<page>.mdx` mapping directly to `https://codra.run/docs/<page>`.
* **Headings with IDs**: Use `<h2 id="my-section">Title</h2>` for major headings to maintain URL anchors and sidebar highlight states.
* **Callout Notes**: Use `<Note type="info">`, `<Note type="tip">`, or `<Note type="warn">` for highlighted admonitions.
* **Code Blocks**: Specify language tags (e.g. `bash`, `ini`, `json`, `yaml`) on all code blocks.
* **SEO Metadata**: Update `docs/docs-seo.ts` when adding or significantly updating guides.

<h2 id="cla">Contributor License Agreement</h2>

Contributors must sign the Contributor License Agreement before a PR can be merged. The CLA is enforced automatically via a GitHub Actions check on all pull requests.

Signing takes 10 seconds via GitHub OAuth. You retain copyright ownership of your contribution. The CLA grants Codra the rights needed to include your work under its dual-licensing model.

  [Sign the CLA](https://codra.run/cla)

<h2 id="security">Security Policy</h2>

Please do not open public issues for security vulnerabilities. Report security issues privately so they can be addressed before public disclosure.

### Reporting

| Method | Contact | Description |
| --- | --- | --- |
| Email | `me@devarshi.dev` | Preferred channel for vulnerability reports. |
| GitHub | Private reporting | Use GitHub's private security advisory feature if enabled on the repository. |

### Security-Sensitive Areas

- GitHub webhook signature verification
- GitHub App private key handling
- OAuth state and session storage in Cloudflare KV
- Dashboard user allowlist enforcement
- CSRF protection on unsafe dashboard/API requests
- Dashboard-managed LLM provider key encryption
- Cloudflare API token scope for model catalog refresh
- Database connection string handling

### License

Codra is licensed under the **GNU Affero General Public License v3.0 (AGPL-3.0)**. If you modify Codra and run it as a network service, the AGPL requires you to make the corresponding source available to users of that service. Contributions are licensed under the same AGPL-3.0 terms, with the additional grants described in the CLA.

The maintainer reserves the right to provide separately licensed hosted editions where permitted by contributor agreements.

  
    <p className="text-base font-medium text-foreground">Back to the beginning</p>
    <p className="text-sm text-foreground/80 mt-1">Start fresh from the overview — architecture, features, and tech stack.</p>
  
  [Overview](https://codra.run/docs)
