Git

Before writing a single configuration line, take two minutes to understand an important conceptual distinction that saves confusion later. Bubble's Settings → Versions is NOT Git. When you click 'Create a new version' or 'Fork the current version' in Bubble's settings, you are creating a snapshot of your Bubble app's state stored in Bubble's proprietary database. This is Bubble's own branching system — useful for testing risky changes — but it produces no Git commits, no diffs, and no connection to any external repository. Do not look for a way to sync Bubble versions to GitHub; no such sync exists. Now, to connect Bubble to GitHub's API, you need a Personal Access Token (PAT). There are two types: Classic PATs and Fine-grained PATs. For most developer portal use cases, a Classic PAT is simpler: Go to GitHub.com → click your profile photo → Settings → scroll to Developer settings (left sidebar) → Personal access tokens → Tokens (classic) → Generate new token (classic). Give the token a descriptive name like 'Bubble App Integration'. Set an expiration date (90 days is a good default — do not set no expiration for security reasons). Select scopes based on what you need: - `repo` — read and write access to private repositories (issue creation, PR management) - `public_repo` — if you only need public repo access (safer, lower risk) - `issues` — read/write issues (included in `repo`) - `actions:write` — if you want to trigger GitHub Actions workflows from Bubble - `read:org` — if you need to list org repos Click 'Generate token'. GitHub shows the token ONCE — copy it immediately to a secure location (password manager). You will not be able to see it again. For fine-grained PATs (more secure), go to Tokens (beta) → Generate new token → select your repository and specific permissions. Fine-grained PATs expire at most 1 year and restrict access to specific repos, making them a better long-term choice for production apps.

In your Bubble editor, click the Plugins tab in the left sidebar. Click 'Add plugins', search for 'API Connector' (by Bubble), and install it — it is free. Click 'API Connector' in your Plugins list to open the configuration panel. Click 'Add another API' and name it 'GitHub'. In the Shared headers section, click 'Add header'. GitHub's REST API accepts two auth header formats for PATs: - Classic PATs: `Authorization: token ghp_yourtokenhere` - Fine-grained PATs and OAuth tokens: `Authorization: Bearer github_pat_yourtokenhere` For the Key field, enter `Authorization`. For the Value field, enter `token ghp_yourtokenhere` (classic) or `Bearer github_pat_yourtokenhere` (fine-grained) — replacing the placeholder with your actual token. Check the 'Private' checkbox on this header row. This is the most important step: the Private flag ensures Bubble's server never sends this header value to the browser, never logs it in Bubble's Logs tab, and never exposes it in the Bubble debugger. Also add a second shared header: Key = `Accept`, Value = `application/vnd.github.v3+json`. This tells GitHub's API you want the v3 JSON response format — without it some endpoints return unexpected data. Leave the Authentication dropdown set to 'None or self-handled' since you are handling auth manually via the header.

1{
2  "method": "GET",
3  "url": "https://api.github.com/user",
4  "headers": {
5    "Authorization": "token <github_pat - Private>",
6    "Accept": "application/vnd.github.v3+json"
7  }
8}

Before building your main data calls, create a simple initialize call to confirm your PAT is working correctly. Click 'Add another call' under the GitHub API group. Name it 'Get Authenticated User'. Set the type to GET. Enter the URL: `https://api.github.com/user`. Set 'Use as' to 'Data'. This endpoint returns information about the authenticated user — login, name, avatar_url, public_repos count, etc. Click 'Initialize call'. Since this call has no dynamic parameters, click 'Send' immediately. If the call succeeds (HTTP 200), Bubble will detect fields: login (text), name (text), avatar_url (text), public_repos (number), created_at (date). These become a Bubble data type you can use in expressions. If you see a 401 Unauthorized response, your PAT is incorrect, expired, or the header format is wrong. Check the Authorization header value — ensure it starts with 'token ' or 'Bearer ' with a space before the token string. If you see 403 Forbidden, the PAT has been revoked or lacks the required scope. Now create your primary data calls. For listing issues: name = 'List Issues', type = GET, URL = `https://api.github.com/repos/<owner>/<repo>/issues`, add query parameters `state` (text, value: 'open'), `per_page` (number, value: 30), `page` (number, value: 1). Set 'Use as' to 'Data'. Initialize with real values for owner, repo, and you should get back a list of issue objects. For triggering GitHub Actions: name = 'Dispatch Workflow', type = POST, URL = `https://api.github.com/repos/<owner>/<repo>/actions/workflows/<workflow_id>/dispatches`, body = `{"ref": "<branch>"}`. Set 'Use as' to 'Action'. GitHub returns 204 No Content on success — Bubble may show an empty response, which is correct.

1GET https://api.github.com/repos/<owner>/<repo>/issues?state=open&per_page=30&page=<page>
2
3POST https://api.github.com/repos/<owner>/<repo>/actions/workflows/<workflow_id>/dispatches
4Content-Type: application/json
5
6{
7  "ref": "<branch_name>"
8}

Bubble's Repeating Group is the right UI component for displaying lists of GitHub data — issues, PRs, repos, or commits. Proper pagination is essential because GitHub limits most endpoints to 30 results per page by default (max 100 with `per_page=100`). In your Bubble editor, click the Design tab and add a Repeating Group element to your page. In the Repeating Group's property panel: - Set Type of content to the GitHub data type you want to display (e.g., 'List Issues') — this should be a data type Bubble detected from your initialize call. - Set Data source to 'Get data from an external API' → select your 'GitHub - List Issues' call. - Map the dynamic parameters: owner = your GitHub org name (hardcoded or from a Bubble input), repo = the repo name, per_page = 30, page = a custom state (see below). For pagination, create a custom state on the page (or on a Group element) called 'current_page' of type Number with a default value of 1. Set the `page` parameter in the Repeating Group's data source to this custom state's value. Add 'Previous' and 'Next' buttons below the Repeating Group. On Next click, add a Workflow action: 'Set state' → current_page = current_page + 1. On Previous click: Set state → current_page = MAX(current_page - 1, 1) to prevent going below page 1. Inside the Repeating Group's cells, add text elements bound to issue fields: - Title text: 'Current cell's List Issues' → title - Number text: '#' + 'Current cell's List Issues' → number - State badge: 'Current cell's List Issues' → state - Date text: 'Current cell's List Issues' → created_at → formatted as 'MMM D, YYYY' GitHub returns date fields as ISO 8601 strings. Bubble typically parses these correctly as Date type during initialization — but if they appear as text, go back to the API Connector, click Initialize, and manually change the field type dropdown from 'Text' to 'Date'.

With data display working, now add write capabilities. Creating an issue and triggering a workflow dispatch are the two most common write actions in developer portal use cases. For creating a GitHub issue from a Bubble form: add an API call named 'Create Issue', type POST, URL = `https://api.github.com/repos/<owner>/<repo>/issues`, body type = JSON body: ```json { "title": "<issue_title>", "body": "<issue_body>", "labels": ["<label_name>"] } ``` Set 'Use as' to 'Action'. Initialize with test values. In your Bubble editor, add a form with an Input for title and a Multiline Input for body. Add a 'Submit' button. In the Workflow for Submit click, add step: Plugins → 'GitHub - Create Issue' → map title = Input Title's value, body = Input Body's value, label = hardcoded label string like 'bug' or 'feature-request'. For triggering a GitHub Actions workflow: add an API call named 'Dispatch Workflow', type POST, URL = `https://api.github.com/repos/<owner>/<repo>/actions/workflows/<workflow_filename>/dispatches`. The workflow_filename is the YAML filename in your .github/workflows/ directory, for example 'deploy.yml'. Body: ```json { "ref": "<branch_name>" } ``` The ref is the branch name to run the workflow on (e.g., 'main'). Your GitHub Actions YAML must include a `workflow_dispatch:` trigger for this to work. A successful dispatch returns 204 No Content — no body. In Bubble, show a success popup after the action runs, using the Workflow condition 'this step has no errors'. For all write actions, go to Data tab → Privacy and confirm Privacy Rules are set on any Bubble data types that store GitHub response data — restrict read access to logged-in users with the appropriate role.

1{
2  "method": "POST",
3  "url": "https://api.github.com/repos/<owner>/<repo>/actions/workflows/<workflow_id>/dispatches",
4  "headers": {
5    "Authorization": "token <github_pat - Private>",
6    "Accept": "application/vnd.github.v3+json",
7    "Content-Type": "application/json"
8  },
9  "body": {
10    "ref": "<branch_name>"
11  }
12}

GitHub API calls consume Bubble Workload Units (WU) — Bubble's post-2023 billing unit for server-side operations. Each API Connector call consumes WU proportional to the call complexity and response size. For a developer portal that displays data on page load and handles user write actions, WU cost is moderate — but if you build a polling mechanism (repeatedly checking GitHub for new issues every few seconds), WU costs can accumulate quickly. Better patterns for staying WU-efficient: 1. Use page-level caching: instead of calling GitHub on every user page load, store recently fetched data in a Bubble database table (Issues data type, last_synced timestamp). Refresh from GitHub only when last_synced is older than 5-10 minutes. This cuts API calls dramatically for apps with multiple concurrent users viewing the same repo data. 2. Avoid live GitHub polling: if you need real-time issue updates, consider using GitHub webhooks to push changes to a Bubble Backend Workflow endpoint (paid plan required) rather than polling the API on an interval. 3. Add Workflow error handling: in each Workflow that calls GitHub, add a second step that only runs 'when step 1 API call returned an error'. Show the user a clear error message: 'GitHub request failed — please try again in a moment.' Check Bubble's Logs tab (left sidebar → Logs) to see the specific HTTP status code returned. Common error scenarios: - 401 Unauthorized: PAT expired or revoked — regenerate and update the API Connector header - 403 Forbidden: PAT lacks the required scope, or the repo is private and the PAT does not have repo access - 404 Not Found: the owner/repo values in your URL are wrong or the repo was renamed - 422 Unprocessable Entity: the issue body or create request is missing required fields - 429 Too Many Requests: rate limit hit (5000 requests/hour for authenticated PATs) — reduce polling frequency Verify the data type Privacy Rules in Data tab → Privacy — any Bubble data type storing GitHub issue or repo data should have rules that restrict access to authenticated users with appropriate permissions.