Integrating with GitHub

Users in organizations on the Spell for Teams plan can create runs and workspaces from or using private GitHub repositories they have access to using Spell's GitHub integration. This page explains how.

Note that this integration is only used for private GitHub repositories. Public GitHub repositories are always available for any run or workspace by default.

Enabling the integration

In order to enable the GitHub integration, your account must satisfy two security requirements.

First, your account must have Manager or Admin rights within your target Spell organization. For further information, refer to the section "Managing User Permissions" in the User Management documentation.

Second, you must be a Organization owner or GitHub App manager of the GitHub organization you are enabling this integration for.

To begin, visit the integrations settings page in the Spell web console and click the "Install" button in the GitHub section.

Empty integrations settings page

This will open a new window on GitHub allowing you to configure this integration for any organization you are a member of:

GitHub select organization modal

After selecting an organization, you will be asked to select one or more repositories you wish to enable access for. You can also choose the "All repositories" option, which enables access for all current and future repositories in your organization:

GitHub select repositories modal

After selecting your repositories and clicking on "Install", you will be led to a screen authorizing this access:

GitHub confirm modal

If the installation is completed successfully, you will be led to page on Spell that says "Installation complete!". You may close this window. After refreshing the web console integrations page, the page should change to include your newly installed integeration:

GitHub manage integration page

Managing the integration

You can add or remove repositories for the list you configured access to using the integration at any time.

To begin, visit the Integrations settings page and click on the gear icon to the right of the GitHub organization whose integration settings you wish to change. This will take you to the GitHub settings page:

GitHub manage integration page

You can enable and disable access to your private repositories on this page. This is also where you would go if you wish to delete the integration entirely.

Using the integration

Private Python packages can be installed in a run or workspace using the --pip, --pip-req, or --github-url flags, or the equivalent fields in the web console. Packages installed this way should start with git+https://github.com/. For example:

$ spell run --pip git+https://github.com/REPOOWNER/REPONAME.git@COMMIT

You may use the egg field in the URL to set the module name explicity (example: git+https://github.com/REPOOWNER/REPONAME.git#egg=spell-private-pip-test). You may use the subdirectory field in the URL to install from a subdirectory in the repo (example: git+https://github.com/REPOOWNER/REPONAME#subdirectory=other_dir). These fields may be combined.