Thanks for your interest in contributing to oss.gg
In this manual we'll walk you through the steps you need to take to get oss.gg and your own GitHub app up and running. It consists of four parts:
- GitHub SSO Configuration (make the login with GitHub work)
- oss.gg Github App Setup (setup your own version of the oss.gg GitHub app)
- Run oss.gg server locally
- Start the local instance of oss.gg with your GitHub test app and install oss.gg on test repository
oss.gg only works with GitHub sign up and login. To make it work locally, you need to fill in these .env variables:
GITHUB_APP_CLIENT_ID=
GITHUB_APP_CLIENT_SECRET=
GITHUB_APP_ACCESS_TOKEN=
Go to your GitHub account Settings -> Developer Settings -> OAuth Apps:
![image](https://private-user-images.githubusercontent.com/72809645/331888029-8d2d2bf3-63ef-4c97-bc94-b08a6a23b515.png?jwt=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJnaXRodWIuY29tIiwiYXVkIjoicmF3LmdpdGh1YnVzZXJjb250ZW50LmNvbSIsImtleSI6ImtleTUiLCJleHAiOjE3MjUwMjM3MTYsIm5iZiI6MTcyNTAyMzQxNiwicGF0aCI6Ii83MjgwOTY0NS8zMzE4ODgwMjktOGQyZDJiZjMtNjNlZi00Yzk3LWJjOTQtYjA4YTZhMjNiNTE1LnBuZz9YLUFtei1BbGdvcml0aG09QVdTNC1ITUFDLVNIQTI1NiZYLUFtei1DcmVkZW50aWFsPUFLSUFWQ09EWUxTQTUzUFFLNFpBJTJGMjAyNDA4MzAlMkZ1cy1lYXN0LTElMkZzMyUyRmF3czRfcmVxdWVzdCZYLUFtei1EYXRlPTIwMjQwODMwVDEzMTAxNlomWC1BbXotRXhwaXJlcz0zMDAmWC1BbXotU2lnbmF0dXJlPTNlZmE4YTVjMTdlNTljZGNmMGVlYmJlOGEwY2M5YTFlMDRkNDFkMzVlMDM2ZWQyODUxYjUzZWIyYjZmNDg4NWImWC1BbXotU2lnbmVkSGVhZGVycz1ob3N0JmFjdG9yX2lkPTAma2V5X2lkPTAmcmVwb19pZD0wIn0.sOvAjP-xY98DXUGD7rSFJbc0iC9QtA0FyoP6r5ZeZkU)
Set it up as follows:
![image](https://private-user-images.githubusercontent.com/72809645/331888069-2c5ea5aa-2ac3-4c20-b389-7c1815ffa040.png?jwt=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJnaXRodWIuY29tIiwiYXVkIjoicmF3LmdpdGh1YnVzZXJjb250ZW50LmNvbSIsImtleSI6ImtleTUiLCJleHAiOjE3MjUwMjM3MTYsIm5iZiI6MTcyNTAyMzQxNiwicGF0aCI6Ii83MjgwOTY0NS8zMzE4ODgwNjktMmM1ZWE1YWEtMmFjMy00YzIwLWIzODktN2MxODE1ZmZhMDQwLnBuZz9YLUFtei1BbGdvcml0aG09QVdTNC1ITUFDLVNIQTI1NiZYLUFtei1DcmVkZW50aWFsPUFLSUFWQ09EWUxTQTUzUFFLNFpBJTJGMjAyNDA4MzAlMkZ1cy1lYXN0LTElMkZzMyUyRmF3czRfcmVxdWVzdCZYLUFtei1EYXRlPTIwMjQwODMwVDEzMTAxNlomWC1BbXotRXhwaXJlcz0zMDAmWC1BbXotU2lnbmF0dXJlPTQ0ZTMxMDY1YTk3ZTA0YTQ3NWE4MTljN2I3MjI3NWU5NWEyMDQ4NjAxYzJiOGU4NGY3MjZhYmQwMTc0OWI1ODMmWC1BbXotU2lnbmVkSGVhZGVycz1ob3N0JmFjdG9yX2lkPTAma2V5X2lkPTAmcmVwb19pZD0wIn0.UjAyBhXndSgLQsvauXATup9IHTazSnTjduu5zzpgWbk)
Fill in these env variables:
GITHUB_APP_CLIENT_ID=
GITHUB_APP_CLIENT_SECRET=
Now go to Personal Access Token:
![image](https://private-user-images.githubusercontent.com/72809645/331888193-56674a44-29b8-4297-9048-4974b50921ce.png?jwt=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJnaXRodWIuY29tIiwiYXVkIjoicmF3LmdpdGh1YnVzZXJjb250ZW50LmNvbSIsImtleSI6ImtleTUiLCJleHAiOjE3MjUwMjM3MTYsIm5iZiI6MTcyNTAyMzQxNiwicGF0aCI6Ii83MjgwOTY0NS8zMzE4ODgxOTMtNTY2NzRhNDQtMjliOC00Mjk3LTkwNDgtNDk3NGI1MDkyMWNlLnBuZz9YLUFtei1BbGdvcml0aG09QVdTNC1ITUFDLVNIQTI1NiZYLUFtei1DcmVkZW50aWFsPUFLSUFWQ09EWUxTQTUzUFFLNFpBJTJGMjAyNDA4MzAlMkZ1cy1lYXN0LTElMkZzMyUyRmF3czRfcmVxdWVzdCZYLUFtei1EYXRlPTIwMjQwODMwVDEzMTAxNlomWC1BbXotRXhwaXJlcz0zMDAmWC1BbXotU2lnbmF0dXJlPWNhODVmM2IwNDBiZmQ1NWQxOThjODllNjEyOTFlOWNhOWM3NTVlMDIwNzg1MDc2OTAyY2M2NDY3ZGYxMTc0MjMmWC1BbXotU2lnbmVkSGVhZGVycz1ob3N0JmFjdG9yX2lkPTAma2V5X2lkPTAmcmVwb19pZD0wIn0.qGaEZrEw0mR6J9TKDa0zGKFLtJaawaF6n76VbVV4TdY)
Generate one and fill it in the env variable.
All set for the GitHub login 💪
Let's setup your oss.gg GitHub App 👇
You need to create your own GitHub app to test the oss.gg functionality you're developing in your test repo.
Stay in your GitHub Account Settings -> Developer Settings -> GitHub Apps and Create a New App:
![image](https://private-user-images.githubusercontent.com/72809645/331888290-b204e4e2-7afe-4faf-ae80-ce1d25f40128.png?jwt=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJnaXRodWIuY29tIiwiYXVkIjoicmF3LmdpdGh1YnVzZXJjb250ZW50LmNvbSIsImtleSI6ImtleTUiLCJleHAiOjE3MjUwMjM3MTYsIm5iZiI6MTcyNTAyMzQxNiwicGF0aCI6Ii83MjgwOTY0NS8zMzE4ODgyOTAtYjIwNGU0ZTItN2FmZS00ZmFmLWFlODAtY2UxZDI1ZjQwMTI4LnBuZz9YLUFtei1BbGdvcml0aG09QVdTNC1ITUFDLVNIQTI1NiZYLUFtei1DcmVkZW50aWFsPUFLSUFWQ09EWUxTQTUzUFFLNFpBJTJGMjAyNDA4MzAlMkZ1cy1lYXN0LTElMkZzMyUyRmF3czRfcmVxdWVzdCZYLUFtei1EYXRlPTIwMjQwODMwVDEzMTAxNlomWC1BbXotRXhwaXJlcz0zMDAmWC1BbXotU2lnbmF0dXJlPWM0MGY4MjQ4YWVjMmNkZjZmMTJkYTc1MjhmMjA2ZDRkNDhiMDBkNzJhYTVlNzIzNDcxYTcxYWMwNTFlMmJiZTImWC1BbXotU2lnbmVkSGVhZGVycz1ob3N0JmFjdG9yX2lkPTAma2V5X2lkPTAmcmVwb19pZD0wIn0.sQoxCiCFzI7wZzzenq2h4RKJJ7JwJd65fyrjfRdXN94)
Set it up as follows:
- Callback URL:
http://localhost:3000/api/auth/callback
- Setup URL:
http://localhost:3000/manage-repos
(Check the Redirect on Update option) - Webhook set to Active and get a URL from
https://smee.io/
by clicking on Start a new channel and then paste the URL in the Webhook URL field. - Disable SSL verification for now
- Hit "Create GitHub App"
- Copy the Client ID and keep it in the
.env
file (at the top of the page) - Generate a Client Secret and keep it in the
.env
file - Generate a Private Key and keep it in the
.env
file - Now Hit the Save Changes button
Fill in these env varibales with the data you get on the app detail page:
GITHUB_APP_WEBHOOK_SECRET
GITHUB_APP_ID
GITHUB_APP_SLUG
Lastly, you need to fill in the GITHUB_APP_PRIVATE_KEY
variable.
This key comes in a .pem file. Open it and copy the code enclosed in double quotes, like so:
![image](https://private-user-images.githubusercontent.com/72809645/331888420-6a903710-d314-4503-8357-8cc11b756fd0.png?jwt=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJnaXRodWIuY29tIiwiYXVkIjoicmF3LmdpdGh1YnVzZXJjb250ZW50LmNvbSIsImtleSI6ImtleTUiLCJleHAiOjE3MjUwMjM3MTYsIm5iZiI6MTcyNTAyMzQxNiwicGF0aCI6Ii83MjgwOTY0NS8zMzE4ODg0MjAtNmE5MDM3MTAtZDMxNC00NTAzLTgzNTctOGNjMTFiNzU2ZmQwLnBuZz9YLUFtei1BbGdvcml0aG09QVdTNC1ITUFDLVNIQTI1NiZYLUFtei1DcmVkZW50aWFsPUFLSUFWQ09EWUxTQTUzUFFLNFpBJTJGMjAyNDA4MzAlMkZ1cy1lYXN0LTElMkZzMyUyRmF3czRfcmVxdWVzdCZYLUFtei1EYXRlPTIwMjQwODMwVDEzMTAxNlomWC1BbXotRXhwaXJlcz0zMDAmWC1BbXotU2lnbmF0dXJlPTE0M2M2NTcwZDc5MGQyYWFiYjFhNmQ2YWQ3Y2I5MmU2YmJhNmYwNjU5MDgyZmM5ZmY0NTc5MWNiMWRkY2Q2NTAmWC1BbXotU2lnbmVkSGVhZGVycz1ob3N0JmFjdG9yX2lkPTAma2V5X2lkPTAmcmVwb19pZD0wIn0.o9MUbOl4pSrV27ONCXf5ebK4p4iuLWVBGEPSEv1SEm0)
All set 👍
- Clone the project
git clone https://github.com/formbricks/oss.gg.git
cd oss.gg
- Install dependencies
pnpm install
- Copy
.env.example
to.env
and fill in the required environment variables
cp .env.example .env
There is a bunch of differnet env variables which aren't always neccessary. I've prefilled the ones most contributors likely don't need in the env-example.
The NEXTAUTH_SECRET
you can generate with the command written in the command below it.
- Start the server
pnpm dev
- Run the Webhook Proxy
smee --url https://smee.io/<your-smee-path> --path /api/github-webhook --port 3000
4. Start the local instance of oss.gg with your GitHub test app and install oss.gg on test repository
Please follow this video: https://youtu.be/KkKwqcw-h-k
#Got stuck?
Please join our Discord and let us know so we can update this guide 🤓: oss.gg/discord