Importing from GitHub and GitLab

Move a repository to Branchscope once: every branch and tag with its full history, and open pull or merge requests as open changes. After the import, nothing is synced, and Branchscope never calls the source again.

Start an import#

In the web app: Import a repository (on the Repositories page, or /import). Fill in:

• the source URL;
• an access token, for a private source: paste one, or pick one of your saved external tokens;
• the new repository's owner, name and visibility.

With the CLI:

bscope repo import https://github.com/acme/billing --wait
# A private source: the token is read from stdin and used for this import only
echo "$GITHUB_TOKEN" | bscope repo import https://github.com/acme/billing --token-stdin --owner acme --wait

With the API: POST /v1/imports with {"url", "owner", "name", "visibility", "token"}.

The repository is created at once, so its name is taken. The repository page shows the import's progress and log while it runs, and refreshes itself.

What comes over#

Source	What's imported
github.com	All branches and tags, and open pull requests as changes
gitlab.com (including subgroups)	All branches and tags, and open merge requests as changes
Any other https:// git URL	All branches and tags

Imported changes:

• Each open pull or merge request becomes an open change with its title and description. The description starts "Imported from … (by @author)".
• Its review is queued like any new change's, so diagrams and findings follow.
• From a fork: its head comes over as a branch pr/<number> (GitHub) or mr/<number> (GitLab).
• Skipped: a pull request whose base branch didn't come over. The log says which.

What doesn't come over:

• issues, comments, reviews and labels;
• Git LFS files. Their pointers come over, and the log says so; Branchscope doesn't store LFS objects yet.

The push guard decides#

An import is a push by you: everything goes through the same push guard as any push, and shows in activity as yours.

• A denial (deny-all is on, for example) stops the import. Nothing is imported, the repository stays empty, and the import shows the guard's message.
• A guard that can't be reached stops it too: imports fail closed, like pushes.
• Protected branches (main by default, as the new repository's rulesets say) are indexed afterwards, so the graph explorer and views work straight away.
• Release tags: the repository gets the Release tags ruleset once its history has come over, so an import brings its v* tags as they are.

Limits and safety#

• Size: sources over 2 GB are refused.
• Empty repositories only: an import never overwrites anything.
• One at a time: each person has one import running at a time; more wait in a queue.
• Your token: a pasted token is used only for this import. It stays in memory, is never stored or logged, and is gone when the import ends. If Branchscope restarts during an import, the import fails; start it again with the token. A saved external token stays saved, encrypted, until you delete it.
• Public sources only: sources must be public https:// hosts. Private network addresses and redirects aren't followed.

When an import fails#

The repository page shows the error and the log. Common causes:

• The source can't be read: a private repository without a token, a token without read access, or a mistyped URL. Fix it and import again under a new name; the failed import's repository stays, empty, until you delete it (its Danger tab).
• The guard denied it: read its message, ask an administrator, and import again.
• Too large: over 2 GB.