Integrating with GitHub

For organizations on the Spell for Teams plan who host their code on GitHub, you can install our GitHub app to allow members of your organization to create runs using private GitHub repositories. This enables runs from the web and runs launched with the --github-url flag to be created without having to publish code publicly to GitHub. This also enables the use of private Python packages with the --pip flag.

This guide will walk through how to set up a GitHub integration for your organization.


If your code is hosted in a public GitHub repository, you do not need to integrate with GitHub to use it in Spell runs! Public repositories are accessible via the web and the --github-url run flag without any additional configuration.

Adding the Integration to Spell


Only managers or admins of a Spell org can add GitHub integrations. GitHub also restricts installation of GitHub apps to GitHub organization owners. Make sure you have the appropriate permissions for both before proceeding.

Navigate to the integrations settings page and click the "Install" button in the GitHub section.

Image of integration settings page

Installing the GitHub App

Clicking on the "Install" button will open a window that will prompt you through GitHub's app installation flow. First, select which account you would like to add the integration to.

Image of GitHub account prompt

GitHub will then prompt you for which repositories you would like to give the app access to. Continue with "All repositories" to give your Spell organization access to all repositories under your chosen GitHub account, or select specific repositories from the dropdown. Hit the "Install" button once you have completed setup.

Image of GitHub repo prompt

You will then be brought to a page to authenticate your GitHub user with Spell. GitHub will prompt you asking to associate your GitHub user to the Spell app. Hit the "Authorize" button to proceed.

Image of GitHub user prompt

Once you have associated your GitHub user to Spell, your installation is complete! Your new installation will be available in your integrations settings page, and any GitHub runs you create will have access to the private repositories that you have set up!

Using Private pip Packages in Runs

Once the GitHub app has been installed to integrate private repositories with Spell, those private repositories can be installed into build environments as a pip package through the --pip flag in the CLI and the Pip Package fields in the web console. Pass the git+https URL to the repository, and Spell will automatically inject the credentials for repositories that the GitHub app has been installed to. For example:

$ spell run --pip git+

For an example application of the private pip packages feature, refer to the blog post "Fine-grained access control in Spell using private pip packages".