How GitHub integration works
Runpod’s GitHub integration simplifies your workflow by pulling your code and Dockerfile from GitHub, building the container image, storing it in Runpod’s secure container registry, and deploying it to your endpoint.Requirements
To deploy a worker from GitHub, you need:- A working handler function in a GitHub repository.
- A Dockerfile in your repository. See Creating a Dockerfile for details.
- A GitHub account.
For an example repository containing the minimal files necessary for deployment, see runpod-workers/worker-basic on GitHub.
Authorizing Runpod with GitHub
Before deploying from GitHub, you need to authorize Runpod to access your repositories:- Open the settings page in the Runpod console.
- Find the GitHub card under Connections and click Connect.
- Sign in using the GitHub authorization flow. This will open your GitHub account settings page.
-
Choose which repositories Runpod can access:
- All repositories: Access to all current and future repositories.
- Only select repositories: Choose specific repositories.
- Click Save.
Deploying from GitHub
To deploy a worker from a GitHub repository:- Go to the Serverless section of the Runpod console
- Click New Endpoint
- Under Import Git Repository, use the search bar or menu to select the repository containing your code. This menu is populated with all repos connected to your account (repos you’ve forked/created, or owned by your GitHub organizations).
-
Configure your deployment options:
- Branch: Select which branch to deploy from.
- Dockerfile Path: Specify the path to your Dockerfile (if not in root).
-
Configure your endpoint settings:
- Enter an Endpoint Name.
- Choose your Endpoint Type: select Queue for traditional queue-based processing or Load Balancer for direct HTTP access (see Load balancing endpoints for details).
- Under GPU Configuration, select the appropriate GPU types for your workload.
- Configure other settings as needed (workers, timeouts, environment variables).
- Click Deploy Endpoint to deploy your worker.
Monitoring build status
You can monitor your build status in the Builds tab of your endpoint detail page. Builds progress through these statuses:Status | Description |
---|---|
Pending | Runpod is scheduling the build. |
Building | Runpod is building your container. |
Uploading | Runpod is uploading your container to the registry. |
Testing | Runpod is testing your Serverless worker. |
Completed | Runpod completed the build and upload. |
Failed | Something went wrong (check build logs). |
Updating your endpoint
When you make changes to your GitHub repository, they won’t automatically be pushed to your endpoint. To trigger an update for the workers on your endpoint, create a new release for the GitHub repository. For detailed instructions on creating releases, see the GitHub documentation.Managing multiple environments
GitHub integration enables streamlined development workflows by supporting multiple environments:- Production endpoint tracking the
main
branch. - Staging endpoint tracking the
dev
branch.
- Create a new branch for your staging endpoint.
- Create an endpoint for your production branch.
- On the Serverless page of the Runpod console, click the three dots to the top right of your production endpoint. Click Clone Endpoint.
- Expand the Repository Configuration section and select your staging branch.
- Click Create Endpoint.
Continuous integration with GitHub Actions
You can enhance your workflow with GitHub Actions for testing before deployment:-
Create a workflow file at
.github/workflows/test-and-deploy.yml
:To add your Runpod API key to a GitHub secret, see Using secrets in GitHub Actions. -
Create test cases for your repository at
.github/tests.json
:
Limitations
Runpod’s GitHub integration has a few limitations to be aware of:GitHub integration limitations
When using GitHub integration with Runpod, be aware of these important limitations:- Build time limit: Builds must complete within 160 minutes (2.5 hours). Optimize your Dockerfile for efficiency with large images to avoid timeouts.
- Image size restriction: Docker images cannot exceed 80 GB. Plan your image requirements accordingly, particularly when including large model weights or dependencies.
- Base image limitations: The integration doesn’t support privately hosted images as base images. Consider incorporating essential components directly into your Dockerfile instead.
- Hardware-specific builds: Builds requiring GPU access during construction (such as those using GPU-compiled versions of libraries like
bitsandbytes
) are not supported. - Platform exclusivity: Images built through Runpod’s image builder service are designed exclusively for Runpod’s infrastructure and cannot be pulled or executed on other platforms.
- Single GitHub connection: Each Runpod account can link to only one GitHub account. This connection cannot be shared among team members, requiring separate Runpod accounts for collaborative projects.
Disconnecting GitHub
To disconnect your GitHub account from Runpod:- Go to Runpod Settings → Connections → Edit Connection
- Select your GitHub account.
- Click Configure.
- Scroll down to the Danger Zone.
- Uninstall “Runpod Inc.”
Troubleshooting deployment issues
If your worker fails to deploy or process requests:- Check the build logs in the Runpod console for error messages.
- Verify your Dockerfile is properly configured.
- Ensure your handler function works correctly in local testing.
- Check that your repository structure matches what’s expected in your Dockerfile.
- Verify you have the necessary permissions on the GitHub repository.