This guide explains how to use the "Deploy Course to qBraid" action to automate your course deployment.
The action performs the following stages:
- Validate API Key: Checks if your
QBRAID_API_KEYis valid. - Validate course.json: Ensures the course configuration file has the correct structure.
- Verify notebooks: Confirms all referenced notebook files exist and validates security.
- Check image references: Validates all images referenced in notebooks exist and are under 1MB.
- Create course: Registers the course with qBraid API using repository metadata.
- Poll for completion: Waits for course processing to complete.
- Notify: Sends notification with the deployed course URL.
Your repository must contain a course.json file in the root with the following structure:
{
"courseName": "Introduction to Quantum Computing",
"courseDescription": "A beginner-friendly course on quantum computing fundamentals",
"visibility": "public",
"imageLink": {
"darkLogo": "assets/images/dark-logo.png",
"lightLogo": "assets/images/light-logo.png"
},
"tags": ["quantum computing", "beginner"],
"deployedTo": ["qbraid.com"],
"content": [
{
"chapterName": "Introduction to Python",
"chapterFileName": "intro.ipynb",
"chapterNumber": 1,
"baseFilePath": "./chapter1/intro.ipynb",
"kernelName": "python3",
"kernelId": "Python 3",
"sections": [
{
"sectionNumber": 1.1,
"sectionName": "Getting Started",
"baseFilePath": "./chapter1/section1/getting_started.ipynb",
"kernelName": "python3",
"kernelId": "Python 3"
}
]
}
]
}- courseName (string): Name of the course
- courseDescription (string): Brief description of the course
- visibility (string): Visibility setting (e.g., "public", "private")
- imageLink (object): Logo image paths for dark and light themes
- darkLogo (string): Repo-relative path to the dark theme logo image (e.g.
assets/images/dark-logo.png) - lightLogo (string): Repo-relative path to the light theme logo image (e.g.
assets/images/light-logo.png)
- darkLogo (string): Repo-relative path to the dark theme logo image (e.g.
- tags (array of strings): List of tags for the course
- deployedTo (array of strings): Deployment targets (allowed: "qbraid.com", "quera.com")
- content (array): List of chapters
- chapterName (string): Display name for the chapter
- chapterFileName (string): Notebook file name for the chapter (e.g.
intro.ipynb) - chapterNumber (number): Chapter number/order
- baseFilePath (string): Path to the chapter notebook from repo root (max 5MB)
- kernelName (string): Jupyter kernel to use (e.g., "python3", "qbraid_python")
- kernelId (string): Display name for the kernel
- sections (array, optional): List of sections within the chapter
- sectionNumber (number): Section number/identifier
- sectionName (string): Display name for the section
- baseFilePath (string): Path to the section notebook from repo root (max 5MB)
- kernelName (string): Jupyter kernel to use
- kernelId (string): Display name for the kernel
Create a workflow file (e.g., .github/workflows/deploy.yml) in your course repository:
name: Deploy Course
on:
push:
branches: [ main ]
workflow_dispatch:
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v6
- uses: courseBuilderNelson/UploadActionRepo@main
with:
api-key: ${{ secrets.QBRAID_API_KEY }}name: Deploy Course
on:
push:
branches: [ main ]
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v6
- uses: courseBuilderNelson/UploadActionRepo@main
with:
api-key: ${{ secrets.QBRAID_API_KEY }}
course-json-path: 'config/course.json'The workflow validates image references in markdown cells. Images can be referenced using:
<img src="./images/photo.jpg" alt="Photo">Note: HTTP/HTTPS URLs are allowed and won't be validated.
- Ensure
QBRAID_API_KEYis set in your repository secrets. - Verify the key is active and correct.
- Ensure
course.jsonmatches the required structure exactly. - Check for missing commas or incorrect field names.
- Verify that file paths in
course.jsonare correct and relative to repository root.
- Check that image files exist at specified paths.
- Ensure your API key has permissions to upload files.
- Check if the file paths contain special characters that might cause issues.
- If the API is slow, increase
QBRAID_REQUEST_TIMEOUT_SECONDSin your workflowenv(default:30).
Example:
jobs:
deploy:
runs-on: ubuntu-latest
env:
QBRAID_REQUEST_TIMEOUT_SECONDS: "60"
steps:
- uses: actions/checkout@v6
- uses: qBraid/upload-course-action@v0.1.0-beta
with:
api-key: ${{ secrets.QBRAID_API_KEY }}
repo-read-token: ${{ secrets.GITHUB_TOKEN }}- Increase polling controls in workflow
envif processing takes longer in staging.
Example:
jobs:
deploy:
runs-on: ubuntu-latest
env:
QBRAID_MAX_POLL_ATTEMPTS: "20"
QBRAID_POLL_INTERVAL_SECONDS: "30"
QBRAID_MAX_CONSECUTIVE_ERRORS: "7"
steps:
- uses: actions/checkout@v6
- uses: qBraid/upload-course-action@v0.1.0-beta
with:
api-key: ${{ secrets.QBRAID_API_KEY }}
repo-read-token: ${{ secrets.GITHUB_TOKEN }}For issues related to:
- Workflow: Open an issue in this repository
- qBraid API: Contact qBraid support
- Course content: Check your course.json and notebook files