Deployment
CI/CD pipeline with GitHub Actions and Vercel
Overview
The deployment system uses GitHub Actions to automate testing, building, and deploying the application to Vercel. Every code change triggers automated workflows that ensure code quality before deployment, and each environment (preview, develop, staging, production) has its own deployment pipeline.
Environments
The application deploys to four distinct environments, each serving a specific purpose in the development lifecycle:
| Environment | URL | Branch | Purpose |
|---|---|---|---|
| Preview | preview-xyz.vercel.app | PR branches | Test features in isolation before merging |
| Develop | dev.odysee.ai | develop | Integration testing with latest merged features |
| Staging | staging.odysee.ai | release/* | Pre-production validation before releasing to users |
| Production | app.odysee.ai | main | Live application serving real users |
Deployment Flow
The deployment process follows the Git Flow branching model, where code progresses through environments as it moves closer to production:
How It Works
Feature Development
Developers create feature branches and open pull requests to develop. Each PR automatically deploys a preview environment for testing.
Integration Testing
Once approved, features merge to develop and deploy to the development environment where they integrate with other recent changes.
Release Preparation
When ready for production, a release branch is created from develop. This deploys to staging for final QA testing.
Production Release
After staging validation, the release branch merges to main, triggering production deployment and creating a GitHub release with changelog.
GitHub Actions Workflows
The CI/CD system consists of multiple workflows that run automatically based on git events.
Workflow Details
CI Workflow
The CI workflow runs on every pull request and push to develop or main. It validates code quality before allowing deployment.
Concurrency Control: The workflow uses cancel-in-progress to automatically cancel previous runs when new commits are pushed. This saves CI minutes and provides faster feedback.
Preview Deployment
Preview deployments create isolated environments for each pull request, allowing reviewers to test changes before merging.
How it works: When you open a PR to develop, GitHub Actions builds the application with Vercel and deploys it to a unique URL. The workflow then comments on the PR with the deployment URL. Each new commit updates the same preview deployment.
Path filtering: The workflow only runs when relevant files change (apps/web/**, packages/ui/**, etc.), avoiding unnecessary deployments for documentation-only changes.
Cleanup: When the PR is closed or merged, the workflow posts a cleanup notice. Vercel automatically removes preview deployments after a period of inactivity.
Develop Deployment
The develop environment serves as an integration testing ground where all merged features come together.
Automatic deployment: Every push to the develop branch triggers a deployment to dev.odysee.ai. This happens automatically after PRs are merged, ensuring the develop environment always reflects the latest code.
Integration testing: Developers and QA teams use this environment to test how features interact with each other before creating a release.
Staging Deployment
Staging provides a production-like environment for final validation before releasing to users.
Release branches: When creating a release branch (e.g., release/v1.0.0), the workflow automatically deploys to staging.odysee.ai. The version is extracted from the branch name.
Bug fixes: Any commits to the release branch update the staging deployment, allowing teams to fix issues discovered during QA without affecting develop or production.
Instructions: The workflow comments on commits with next steps, reminding teams to test thoroughly before creating a PR to main.
Production Release
The production workflow handles the final deployment and creates a versioned GitHub release.
Extract Version
The workflow extracts the version number from the merged release branch name (e.g., release/v1.0.0 → v1.0.0).
Create Git Tag
Creates and pushes a git tag with the version number. This tag marks the exact commit deployed to production.
Generate Changelog
Uses git-cliff to automatically generate a changelog from commit messages between releases. The changelog follows conventional commit format.
Create GitHub Release
Creates a GitHub release with the generated changelog. The release includes the tag, changelog, and deployment timestamp.
Deploy to Production
Builds and deploys the application to app.odysee.ai using Vercel's production environment. Only stable releases (non-prerelease) deploy to production.
Cleanup
A separate workflow merges the release branch back to develop and deletes the remote release branch, completing the release cycle.
Environment Variables
The application uses different environment variables for each environment, configured in Vercel:
Configure these in GitHub Settings → Secrets and Variables → Actions:
Vercel Configuration
VERCEL_TOKEN- Vercel API token for deploymentsVERCEL_ORG_ID- Your Vercel organization IDVERCEL_PROJECT_ID- Project ID for each environment
Application Secrets
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY- Clerk authenticationCLERK_SECRET_KEY- Clerk server-side keyNEXT_PUBLIC_API_URL- Backend API URLNEXT_PUBLIC_NOVU_APPLICATION_IDENTIFIER- Novu notifications
Configure in Vercel Dashboard → Project Settings → Environment Variables:
| Variable | Preview | Development | Staging | Production |
|---|---|---|---|---|
NEXT_PUBLIC_APP_URL | Preview URL | dev.odysee.ai | staging.odysee.ai | app.odysee.ai |
NEXT_PUBLIC_AUTH_STRATEGY | clerk | clerk | clerk | clerk |
NEXT_PUBLIC_LOG_LEVEL | debug | debug | info | error |
These variables automatically switch based on the deployment environment.
Get Vercel IDs:
- Install Vercel CLI:
npm i -g vercel - Login:
vercel login - Link project:
vercel link - Get Project ID:
cat .vercel/project.json - Get Org ID:
vercel whoami
Add these IDs to GitHub Secrets to enable automated deployments.
Deployment Process
Feature Development
Create Feature Branch
git checkout -b feature/user-authDevelop & Commit
Make changes and commit following conventional commit format.
Push & Create PR
git push origin feature/user-authOpen a PR to develop. GitHub automatically creates a preview deployment.
Review Preview
Visit the preview URL in the PR comment to test your changes in isolation.
Merge
After approval, merge the PR. The feature automatically deploys to the develop environment.
Release Process
Create Release Branch
git checkout develop
git pull origin develop
git checkout -b release/v1.0.0
git push origin release/v1.0.0The release automatically deploys to staging.
Test on Staging
Visit staging.odysee.ai and perform thorough QA testing.
Fix Bugs (if needed)
Commit fixes directly to the release branch. Each commit updates staging.
Create PR to Main
Open a PR from the release branch to main. After approval and merge:
- Deploys to production
- Creates GitHub release with changelog
- Merges back to develop
- Deletes release branch
Monitoring & Troubleshooting
Vercel Dashboard
Monitor deployments in real-time at Vercel Dashboard. View deployment status, build logs, function logs, and performance metrics.
GitHub Actions
Track workflow runs in the repository's Actions tab. View running workflows, build logs, deployment status, and failed jobs.
Common Issues
Performance Optimizations
Turborepo Caching
Turborepo caches build outputs based on file contents and task configuration. When files haven't changed, Turborepo skips rebuilding that package entirely, dramatically speeding up CI runs.
Benefits: Skip unchanged package builds, share cache across CI runs, and get faster deployments.
Vercel Build Cache
Vercel automatically caches node_modules, .next/cache, and the pnpm store between builds. This reduces installation and build times significantly.
First build: ~5-10 minutes. Cached builds: ~2-3 minutes.
Best Practices
Rollback Strategy
If a production deployment causes issues, you can quickly rollback:
Instant Rollback:
- Go to Vercel Dashboard → Deployments
- Find the previous working deployment
- Click "Promote to Production"
This instantly switches production to the previous version without requiring a new build or deployment.
Code Revert:
git revert <commit-hash>
git push origin mainThis creates a new commit that undoes the problematic changes and triggers a new production deployment. Maintains git history.
Avoid force pushing to main. Use git revert to maintain commit history and allow proper auditing.
You now have a complete understanding of the CI/CD pipeline. For questions or issues, check the GitHub Actions logs or reach out to the engineering team.