Skip to main content
OWASP Nest makes it easy to find and contribute to OWASP projects. This guide walks you through the entire contribution process, from setup to pull request.

​
Prerequisites

Before contributing to OWASP projects through Nest, ensure you have:

Docker

Required for running Nest locally

pre-commit

Automates code quality checks

Git

Version control for your contributions

GitHub Account

Required to submit pull requests
Windows Users: WSL (Windows Subsystem for Linux) is required. Use the WSL terminal, not PowerShell, to avoid setup issues.

​
Getting Started

1

Star and Fork the Repository

Start by starring the project on GitHub to show your support, then fork it to your account.
# Clone your fork
git clone https://github.com/<your-account>/<repository-name>
cd <repository-name>
2

Set Up Your Development Environment

Copy the environment files and configure them:
# Backend environment
cp backend/.env.example backend/.env

# Frontend environment
cp frontend/.env.example frontend/.env
Ensure all .env files are saved in UTF-8 format without BOM to prevent “Unexpected character” errors.
3

Configure Algolia Search

  1. Create a free account at Algolia
  2. Get your Application ID and Write API Key from the dashboard
  3. Update backend/.env:
DJANGO_ALGOLIA_APPLICATION_ID=<your-application-id>
DJANGO_ALGOLIA_WRITE_API_KEY=<your-write-api-key>
4

Run the Application

Start the development environment (this must remain running):
make run
Wait until the API responds at http://localhost:8000/api/v0
5

Load Initial Data

Open a new terminal session and populate the database:
# Load fixtures (requires gzip)
make load-data

# Index data in Algolia
make index-data
6

Verify Setup

Check that these endpoints are accessible:

​
Contribution Workflow

1

Find or Create an Issue

  • Browse the Issues tab for open issues
  • Look for good first issue labels if you’re new to the project
  • Found a bug? Create a new issue describing the problem
You must be assigned to an issue before submitting a PR. PRs without assignment will be automatically closed.
2

Sync Your Fork

Before starting work, ensure your fork is up to date:
# Add upstream remote (first time only)
git remote add upstream https://github.com/OWASP/Nest.git

# Update your local main branch
git checkout main
git fetch upstream
git merge upstream/main
3

Create a Feature Branch

Always work in a separate branch:
git checkout -b feature/my-feature-name
4

Make Your Changes

  • Write clean, well-documented code
  • Add tests for new functionality
  • Ensure your changes only include related files
  • Follow the existing code style and patterns
5

Run Quality Checks

This is a required step - you will not be assigned to new issues if you skip this:
make check-test
This command runs:
  • Code linters (frontend and backend)
  • Static analysis tools
  • Test suites
  • Coverage checks
Your PR won’t be reviewed until all checks pass and meet coverage thresholds.
6

Commit Your Changes

Write meaningful commit messages:
git add .
git commit -m "Add feature: concise description of changes"
7

Push to Your Fork

git push origin feature/my-feature-name
8

Create a Draft Pull Request

  1. Go to the original repository on GitHub
  2. Click “New Pull Request”
  3. Select your fork and branch
  4. Mark it as a Draft PR
  5. Wait for automated checks to complete
9

Address Automated Review Comments

Review and resolve all comments from:
  • CodeRabbit: Code quality suggestions
  • SonarQube: Security and maintainability issues
  • GitHub Advanced Security: Security vulnerabilities
If you disagree with a suggestion, mark it as resolved with a brief explanation.
10

Mark PR as Ready for Review

Once all automated comments are resolved and CI/CD passes:
  1. Mark the PR as “Ready for Review”
  2. Request review from project maintainers
  3. Wait for human reviewers’ feedback
11

Address Reviewer Feedback

  • If maintainers request changes, mark the PR as Draft again
  • Make the requested changes
  • Run make check-test again
  • Push updates and mark as Ready for Review

​
Optional: Fetching GitHub Data

If you need to work with live GitHub data:
1

Create a Superuser

make create-superuser
2

Generate GitHub Token

Create a personal access token on GitHub.
3

Update Environment

Add the token to backend/.env:
GITHUB_TOKEN=<your-github-token>
4

Sync Data

make sync-data

​
Testing Your Contributions

​
Run All Tests

make test

​
Run Specific Test Types

make test-frontend

​
Test Coverage Requirements

  • Backend: Minimum coverage defined in backend/pyproject.toml
  • Frontend: Minimum coverage defined in frontend/jest.config.ts
PRs that decrease overall test coverage will not be merged.

​
Accessing Internal Dashboards

Some features require specific permissions for local development:
  1. Start the backend and open Django Admin at http://localhost:8000/a
  2. Navigate to GitHub Users and open your user record
  3. Enable the is_owasp_staff checkbox in the Permissions section
  4. Clear browser cookies for localhost:3000
  5. Sign in again - the dashboard will appear in the user menu
Option 1: As Project Leader
  1. Open Django Admin → OWASP → Projects
  2. Open or create a project
  3. Add your GitHub username to the leaders_raw field
Option 2: As Mentor
  1. Open Django Admin → Mentorship → Mentors
  2. Click Add Mentor
  3. Select your GitHub user
After either option, clear cookies and sign in again.

​
Troubleshooting

This error occurs when .env files have incorrect encoding.Solution: Open each .env file in VS Code:
  1. Click the encoding indicator in the bottom-right corner
  2. Select “Save with Encoding”
  3. Choose “UTF-8” (not “UTF-8 with BOM”)
  4. Restart with make run
Ensure:
  • WSL integration is enabled in Docker Desktop
  • You’re using WSL terminal, not PowerShell
  • Project is not cloned under /mnt/c (Windows C: drive)
Verify:
  • Your API key has addObject permission
  • Application ID and API Key are correct in backend/.env
  • You’re using the Write API Key, not the Search API Key

​
Code of Conduct

All contributors must follow the OWASP Code of Conduct. Be respectful, inclusive, and professional in all interactions.

​
Getting Help

If you encounter issues:
  1. Check the Troubleshooting section
  2. Search existing GitHub Issues
  3. Ask in the project’s discussion forums
  4. Reach out to project maintainers
Start with good first issue labels to get familiar with the contribution process!

Build docs developers (and LLMs) love

Get started for freeTalk to us