Connect GitHub.com repositories to Swimm

On this page

When you create a new workspace, it will consist of a single repository - Swimm's (demo) todo repo.

Getting started​

Add a repository​

Click the + Add new... button in the sidebar. Select Repo.

Permissions​

By default, Swimm admins can connect repositories to the workspace. Non-admins can be granted permissions to add repositories to the workspace in Workspace settings -> Members.

Connect your repository.​

Two options:

1. To add public or private repositories, choose Select from all repositories.
2. To only add public repositories, choose Select from public repositories.

Click on Allow GitHub Access to OAuth into your GitHub account.

We never store your code or your docs on our server. Read more about our security and privacy overview.

Log into GitHub​

Select or search for the repositories​

Select and connect your repository (or multiple repositories) to your Swimm workspace.

Voila! Now that you have successfully added your repositories, go create your first Swimm document.

How to bulk add repositories​

Refer to our Add Repo API to add repositories in bulk.

Troubleshooting​

If you don't see the repository you wish to add, Swimm doesn't have the correct permissions required and you’ll need to click the Manage Scope button at the bottom right of the dialog box.

If you still cannot locate your repo, please reach out to us on our Community Slack Channel.

Authorizing Swimm's OAuth App​

Swimm installs GitHub's OAuth App to read and write documentation on your behalf. To allow access to a repository, an owner of the organization needs to approve the app.

GitHub organization members and outside collaborators can request that an owner approve access to the organization resources for OAuth apps.

• See GitHub's documentation for instructions to request organization approval for OAuth apps.

As an owner of the organization in GitHub, follow these instructions to approve Swimm's OAuth app for your organization members/collaborators.

To view a list of the people in your organization and filter by their role within GitHub, follow GitHub's documentation.

Understanding GitHub's 'Organization access'​

When authorizing Swimm's OAuth app, you may see all organizations you are part of, alongside a mark next to each of them:

Authorization status for your organization:​

Owner authorized Swimm​

• The organization is marked with a green checkmark ✅. For example, see swimmio in the image above.

Nobody has requested to authorize Swimm and you are not the owner of the organization​

• You will see a Request button next to the organization. For example, learn-co-students in the image above.

Someone has requested to authorize Swimm​

• A Request pending text will appear instead of the Request button.

You are an owner of the organization​

• You will see a Grant button to authorize Swimm. If another owner of the organization has declined any previous request to authorize Swimm, you will see a red ❌ next to the organization.

As an owner of the organization, follow these instructions to authorize Swimm.

How to change the order of repositories​

You can change the order of repositories displayed on the left-side navigation. Hover over any repository and drag the repository using the arrow icon.

Changing the order of your repositories only affects your Swimm account and not other Swimmers.

• Getting started
  • Add a repository
  • Connect your repository.
  • Log into GitHub
  • Select or search for the repositories
  • How to bulk add repositories
• Troubleshooting
  • Authorizing Swimm's OAuth App
  • Understanding GitHub's 'Organization access'
• How to change the order of repositories

---

Read this article on Swimm's official docsite