Skip to content

Add GitHub build args (mintlify version) #277

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 5 commits into
base: main
Choose a base branch
from
Open
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
188 changes: 113 additions & 75 deletions serverless/workers/github-integration.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -13,25 +13,20 @@ Runpod's GitHub integration simplifies your workflow by pulling your code and Do

To deploy a worker from GitHub, you need:

* A working [handler function](/serverless/workers/handler-functions) in a GitHub repository.
* A Dockerfile in your repository. See [Creating a Dockerfile](/serverless/workers/deploy#creating-a-dockerfile) for details.
* A GitHub account.
- A working [handler function](/serverless/workers/handler-functions) in a GitHub repository.
- A Dockerfile in your repository. See [Creating a Dockerfile](/serverless/workers/deploy#creating-a-dockerfile) for details.
- A GitHub account.

## Authorizing Runpod with GitHub

Before deploying from GitHub, you need to authorize Runpod to access your repositories:

1. Open the [settings page](http://runpod.io/console/user/settings) in the Runpod console.

2. Find the **GitHub** card under **Connections** and click **Connect**.

3. Sign in using the GitHub authorization flow. This will open your GitHub account settings page.

4. Choose which repositories Runpod can access:

* **All repositories:** Access to all current and future repositories.
* **Only select repositories:** Choose specific repositories.

5. Click **Save**.

You can manage this connection using Runpod settings or GitHub account settings, in the **Applications** tab.
Expand All @@ -41,26 +36,68 @@ You can manage this connection using Runpod settings or GitHub account settings,
To deploy a worker from a GitHub repository:

1. Go to the [Serverless section](https://www.runpod.io/console/serverless) of the Runpod console

2. Click **New Endpoint**

3. Under **Custom Source**, select **GitHub Repo**, then click **Next**

4. 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).

5. Configure your deployment options:

* **Branch:** Select which branch to deploy from.
* **Dockerfile:** Specify the path to your Dockerfile (if not in root).

- **Branch:** Select which branch to deploy from.
- **Dockerfile:** Specify the path to your Dockerfile (if not in root).
6. (Optional) Enter a custom name for your endpoint.

7. Configure your compute resources (GPU type, worker count, etc.).

8. Click **Create Endpoint**.

Runpod will build your Docker image and deploy it to your endpoint automatically. You'll be redirected to the endpoint details page when complete.

## GitHub build arguments

When deploying a worker from a GitHub repo, you can use specify build arguments for your Dockerfile using `ARG`, allowing you to parameterize values in your Dockerfile instructions. Unlike environment variables, these variables do not persist into the final container, so they won't affect your handler function code.

You can specify build arguments either in your Dockerfile, or using the RunPod UI.

<Note>

For comprehensive information about using `ARG`, refer to the [official Docker documention](https://docs.docker.com/build/building/variables/).

</Note>

### Using build arguments in your Dockerfile

To use build arguments in your Dockerfile, declare variables using the `ARG` keyword, then reference them using `$` syntax.

For example:

```dockerfile
# Base image from RunPod's container registry
ARG CUDA_VERSION=11.8.0
ARG BASE_VERSION=0.6.3

# Use build arguments to specify the base image version
FROM runpod/base:${BASE_VERSION}-cuda${CUDA_VERSION}
```

You must declare an ARG in your Dockerfile before you can reference it, even if you've defined it in the RunPod UI.

### Setting build arguments in the RunPod UI

To customize your build arguments without modifying your Dockerfile, you can specify them using the RunPod console.

When [deploying a worker](#deploying-from-github) from GitHub:

1. During the endpoint configuration process, find the **Build Args** section (below **Public Environment Variables**).
2. Enter key-value pairs for your build arguments.
3. These will be passed to your Docker build process.

You must declare an `ARG` in your Dockerfile before you can reference it, even if you've defined it in the RunPod UI:

```dockerfile
# Build arguments defined in the UI must still be declared in your Dockerfile
ARG CUDA_VERSION
ARG BASE_VERSION

# Use build arguments to specify the base image version
FROM runpod/base:${BASE_VERSION}-cuda${CUDA_VERSION}
```

## Monitoring build status

You can monitor your build status in the **Builds** tab of your endpoint detail page. Builds progress through these statuses:
Expand All @@ -78,8 +115,8 @@ You can monitor your build status in the **Builds** tab of your endpoint detail

GitHub integration enables streamlined development workflows by supporting multiple environments:

* Production endpoint tracking the `main` branch.
* Staging endpoint tracking the `dev` branch.
- Production endpoint tracking the `main` branch.
- Staging endpoint tracking the `dev` branch.

To set up multiple environments:

Expand All @@ -97,66 +134,67 @@ You can enhance your workflow with GitHub Actions for testing before deployment:

1. Create a workflow file at `.github/workflows/test-and-deploy.yml`:

```yml
name: Test and Deploy

on:
push:
branches: [ main ]
pull_request:
branches: [ main ]

jobs:
test-and-deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3

- name: Build and push Docker image
uses: docker/build-push-action@v4
with:
context: .
push: true
tags: [DOCKER_USERNAME]/[WORKER_NAME]:${{ github.sha }}
```yaml
name: Test and Deploy

on:
push:
branches: [ main ]
pull_request:
branches: [ main ]

jobs:
test-and-deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3

- name: Run Tests
uses: runpod/runpod-test-runner@v1
with:
image-tag: [DOCKER_USERNAME]/[WORKER_NAME]:${{ github.sha }}
runpod-api-key: ${{ secrets.RUNPOD_API_KEY }} # Add your API key to a GitHub secret
test-filename: .github/tests.json
request-timeout: 300
```
- name: Build and push Docker image
uses: docker/build-push-action@v4
with:
context: .
push: true
tags: [DOCKER_USERNAME]/[WORKER_NAME]:${{ github.sha }}

- name: Run Tests
uses: runpod/runpod-test-runner@v1
with:
image-tag: [DOCKER_USERNAME]/[WORKER_NAME]:${{ github.sha }}
runpod-api-key: ${{ secrets.RUNPOD_API_KEY }} # Add your API key to a GitHub secret
test-filename: .github/tests.json
request-timeout: 300
```

<Tip>

<Tip>
To add your Runpod API key to a GitHub secret, see [Using secrets in GitHub Actions](https://docs.github.com/en/actions/security-for-github-actions/security-guides/using-secrets-in-github-actions).

To add your Runpod API key to a GitHub secret, see [Using secrets in GitHub Actions](https://docs.github.com/en/actions/security-for-github-actions/security-guides/using-secrets-in-github-actions).
</Tip>

</Tip>

2. Create test cases for your repository at `.github/tests.json`:

```json
[
{
"input": {
"prompt": "Test input 1"
},
"expected_output": {
"status": "COMPLETED"
}
},
{
"input": {
"prompt": "Test input 2",
"parameter": "value"
```json
[
{
"input": {
"prompt": "Test input 1"
},
"expected_output": {
"status": "COMPLETED"
}
},
"expected_output": {
"status": "COMPLETED"
{
"input": {
"prompt": "Test input 2",
"parameter": "value"
},
"expected_output": {
"status": "COMPLETED"
}
}
}
]
```
]
```

## Limitations

Expand Down Expand Up @@ -197,7 +235,7 @@ If your worker fails to deploy or process requests:

After deploying your worker from GitHub, you can:

* [Send API requests to your endpoint.](/serverless/endpoints/send-requests)
* [Create more advanced handler functions.](/serverless/workers/handler-functions)
* [Optimize your endpoint configurations.](/serverless/endpoints/endpoint-configurations)
* [Learn how to deploy workers from Docker Hub.](/serverless/workers/deploy)
- [Send API requests to your endpoint.](/serverless/endpoints/send-requests)
- [Create more advanced handler functions.](/serverless/workers/handler-functions)
- [Optimize your endpoint configurations.](/serverless/endpoints/endpoint-configurations)
- [Learn how to deploy workers from Docker Hub.](/serverless/workers/deploy)