GitScape API is the official backend for GitScape, a platform for generating structured digests and summaries from any git repository. This API powers the GitScape Web frontend and is designed for extensibility, performance, and ease of deployment (notably on Google Cloud Run).
- Main repo: https://github.com/jmxt3/Git-Scape-Web
- Live site: https://gitscape.ai/
main.py– FastAPI entrypoint, defines API and WebSocket endpoints.converter.py– Core logic for cloning, analyzing, and digesting git repositories.app/– Application package:api.py– FastAPI app factory and CORS setup.config.py– Environment and settings management.
requirements.txt/pyproject.toml– Python dependencies.Dockerfile– Containerization for deployment..env.example– Example environment configuration.
GET /– Health check and welcome message.GET /converter– Clone a git repo and return a Markdown digest (blocking HTTP).WS /ws/converter– WebSocket endpoint for real-time progress and digest streaming.
See the OpenAPI docs when running locally for full details.
- Clone the repo:
git clone https://github.com/jmxt3/Git-Scape-API.git cd Git-Scape-API - Install Python 3.10+ and Poetry or use
pip:python3 -m venv venv source venv/bin/activate pip install -r requirements.txt - Copy environment config:
cp .env.example .env # Edit .env as needed - Run the API locally:
uvicorn main:app --host 0.0.0.0 --port 8000 --reload # or fastapi dev - Access docs:
- Swagger UI: http://localhost:8000/docs
- ReDoc: http://localhost:8000/redoc
Tests are not yet included. PRs for test coverage are welcome!
- Follow PEP8 and use black for formatting.
- Use type hints and docstrings for all public functions.
- Keep API endpoints and business logic separated (see
main.pyvsconverter.py).
- Fork this repo and create a feature branch.
- Make your changes with clear commit messages.
- Ensure your code is formatted and type-checked.
- Open a pull request with a clear description.
- For bugs or feature requests, open a GitHub Issue.
- Main web repo: https://github.com/jmxt3/Git-Scape-Web
- Website: https://gitscape.ai/
- Issues: https://github.com/jmxt3/Git-Scape-API/issues
fastapi dev or uvicorn main:app --host 0.0.0.0 --port 8000 --reload
uvicorn main:app --host 0.0.0.0 --port 8000 --workers 4
docker ps docker build -t git_scape_api . docker images docker run -d -p 8080:8080 --name git_scape_container git_scape_api
docker stop git_scape_container docker rm git_scape_container docker rmi git_scape_api
- RESTful API with CRUD operations
- Interactive API documentation with Swagger UI
- Health check endpoint for 855A monitoring
- Docker containerization for Cloud Run deployment
- Environment variable configuration
These are general steps you would follow to deploy this application to Google Cloud Run. You'll need gcloud CLI installed and configured.
-
Enable APIs:
- Ensure the Cloud Run API and Artifact Registry API (or Container Registry API) are enabled for your Google Cloud project.
gcloud services enable run.googleapis.com gcloud services enable artifactregistry.googleapis.com
-
Authenticate gcloud:
- If you haven't already, authenticate the
gcloudCLI:
gcloud auth login gcloud auth configure-docker
(You might need to specify a region for Docker, e.g.,
gcloud auth configure-docker us-central1-docker.pkg.dev) - If you haven't already, authenticate the
-
Set Project ID:
- Set your current project (replace
YOUR_PROJECT_ID):
gcloud config set project YOUR_PROJECT_ID - Set your current project (replace
-
Build the Docker Image:
- Navigate to the directory containing
main.py,Dockerfile, andrequirements.txt. - Build the image using Cloud Build (recommended) or locally with Docker.
-
Using Cloud Build (builds in the cloud and pushes to Artifact Registry): Replace
YOUR_REGION,YOUR_PROJECT_ID, andYOUR_IMAGE_NAME.gcloud builds submit --tag YOUR_REGION-docker.pkg.dev/YOUR_PROJECT_ID/REPOSITORY_NAME/YOUR_IMAGE_NAME:latest .(If you don't have an Artifact Registry repository, you'll need to create one first:
gcloud artifacts repositories create REPOSITORY_NAME --repository-format=docker --location=YOUR_REGION) -
Building locally with Docker (then push):
docker build -t YOUR_REGION-docker.pkg.dev/YOUR_PROJECT_ID/REPOSITORY_NAME/YOUR_IMAGE_NAME:latest . docker push YOUR_REGION-docker.pkg.dev/YOUR_PROJECT_ID/REPOSITORY_NAME/YOUR_IMAGE_NAME:latest
-
- Navigate to the directory containing
-
Deploy to Cloud Run:
- Deploy the container image to Cloud Run. Replace placeholders.
gcloud run deploy YOUR_SERVICE_NAME \ --image YOUR_REGION-docker.pkg.dev/YOUR_PROJECT_ID/REPOSITORY_NAME/YOUR_IMAGE_NAME:latest \ --platform managed \ --region YOUR_DEPLOY_REGION \ --allow-unauthenticated \ --project YOUR_PROJECT_IDYOUR_SERVICE_NAME: A name for your Cloud Run service (e.g.,my-fastapi-app).YOUR_DEPLOY_REGION: The region where you want to deploy (e.g.,us-central1).--allow-unauthenticated: Makes the service publicly accessible. Remove this if you want to manage access via IAM.
-
Access Your Service:
- After deployment, Cloud Run will provide a URL for your service. You can access your FastAPI app at that URL.
Important Considerations for Cloud Run:
- PORT Environment Variable: Cloud Run sets a
PORTenvironment variable that your application must listen on. TheDockerfile'sCMDhandles this by using${PORT:-8080}, which means it will use thePORTvariable if set, or default to8080otherwise. - Statelessness: Cloud Run services should be stateless. Any persistent state should be stored in external services like Cloud SQL, Firestore, or Cloud Storage.
- Concurrency: Configure concurrency settings based on your application's needs.
- Logging & Monitoring: Cloud Run integrates with Cloud Logging and Cloud Monitoring. Standard output (
printstatements, logging libraries) will be captured.
This project is licensed under the MIT License.
Created by João Machete and contributors.
If you like this project, please ⭐️ the repo and share your feedback!