GitHub Sync & Integration

Alph notebooks can be connected to GitHub repositories — push changes, pull updates, create PRs, and view diffs without leaving the editor. This notebook walks through the full GitHub integration.

Connecting a Notebook to GitHub

Step 1: Install the GitHub App

Before you can sync, your organization needs the Alph GitHub App installed:

1. Go to your org's Integrations page (/your-org/~/integrations)
2. Click Connect GitHub
3. Choose your GitHub account or organization
4. Select which repositories Alph can access (all or specific repos)
5. Authorize the app — you'll be redirected back to Alph

You only need to do this once per GitHub account. Multiple notebooks can use the same installation.

Step 2: Connect a Notebook to a Repo

With the GitHub App installed, connect any notebook:

1. Open a notebook in the editor
2. Click Connect to repo in the toolbar
3. Select your GitHub account (if you have multiple installations)
4. Choose the repository from the dropdown
5. Set the file path — where the .ipynb file will live in the repo (e.g., notebooks/my-analysis.ipynb)
6. Set the branch (defaults to main)
7. Click Connect & Push — this pushes the notebook to GitHub

If the file already exists at that path, you'll be asked whether to overwrite it.

---

Sync Status

Once connected, the editor toolbar shows a sync status indicator. It tells you at a glance whether your local notebook and the GitHub copy are in sync:

Click the refresh button next to the status indicator to re-check.

---

Pulling Changes

Notebooks are auto-synced, so connected notebooks in Alph will automaticaly update after any change to the notebook in the repo.

If auto-sync is disabled, new commits (status shows Behind) can be manually pulled the latest version:

1. Click the Pull button in the toolbar
2. Alph fetches the file from GitHub and updates your notebook

If you have unsaved local changes, you'll see a confirmation dialog before pulling. Pulling replaces your local content with the remote version.

Force pull: If you want to re-fetch even when already synced, the pull action supports forcing a refresh.

---

Pushing Changes

When you've made local edits (status shows Ahead), push your changes to GitHub:

1. Click the Push button in the toolbar
2. Enter a commit message (a default is generated for you)
3. Choose your push method:

Direct push

Commits directly to the connected branch. Fast and simple — ideal when you're the only one editing.

Create a pull request

Check "Create a new branch and start a pull request" to push to a new branch and open a PR instead. You'll be asked for a branch name. This is the safer option when collaborating — your teammates can review the changes before merging.

After pushing, Alph gives you a link to the commit or PR on GitHub.

---

Viewing Diffs

Before pushing or pulling, you can preview exactly what's changed. Click the diff button (branch icon) in the toolbar to open the diff viewer.

The diff viewer shows:

• Cell-level changes — which cells were added, removed, or modified
• Line-level changes — color-coded insertions (green) and deletions (red) within each cell
• Direction — toggle between incoming (what you'd pull from GitHub) and outgoing (what you'd push)

Changed cells are expanded by default. Unchanged cells are collapsed — click to expand. Use Expand All / Collapse All to control the view.

Each cell gets a badge:

---

Conflict Resolution

Conflicts happen when both you and someone else have changed the notebook since the last sync. The status shows Diverged.

When you try to push with a conflict, Alph shows a "Repository Has Changed" dialog with two options:

Before choosing, use the diff viewer to compare versions and decide which changes to keep.

Tip: Use the Create PR option instead of force pushing. This preserves both versions and lets your team decide how to merge.

---

Auto-Sync

When auto-sync is enabled (the default), Alph automatically updates your notebook when someone pushes to the connected branch on GitHub — via a webhook. You don't have to manually pull.

If you have local changes when a webhook fires, Alph skips the auto-update to avoid overwriting your work. Once you push or discard your local changes, the next webhook will update normally.

Pause & Resume

You can pause auto-sync without disconnecting:

• Click the settings menu (gear icon) in the sync toolbar
• Select Disable auto-sync — the status shows a bell-off icon
• Manual pull/push still works as usual
• Select Enable auto-sync to resume

Full Disconnect

To completely remove the GitHub connection:

• Settings menu → Disconnect
• This removes all sync metadata but keeps your notebook content
• You can reconnect later to the same or a different repo

---

Browsing GitHub Notebooks

You can browse public notebooks from any GitHub repo directly on Alph, without importing them:

runalph.ai/github/{owner}/{repo}

This lists all .ipynb files in the repo. Click any file to view it in the Alph notebook viewer — rendered with full markdown, code highlighting, and interactive outputs.

You can also link to a specific branch or file:

runalph.ai/github/{owner}/{repo}/tree/{branch}
runalph.ai/github/{owner}/{repo}/blob/{branch}/path/to/notebook.ipynb

This is a great way to share notebook previews — anyone can view them without a GitHub account or Jupyter installed.

---

Practical Workflow

Here's a typical workflow for a team using GitHub sync with Alph:

---

Quick Reference

---

Next: Embed Notebooks