• Documentation
  • Integrations
  • GitHub App

GitHub App

Integrating CodeSandbox and GitHub using our GitHub App allows you to streamline your development and review process.

This higher level of integration offers several benefits to your project:

  • Automatically add links to open your code in CodeSandbox or jump straight to a preview of the running code from any pull request
  • Add previews of the running code as Deployments in the GitHub UI, enabling access for reviewers and CI tools

We're always looking for ways to make CodeSandbox a seamless part of your development workflow, and our GitHub App is the best way to take advantage.

Pull Request Links

The integration of CodeSandbox and GitHub allows you to automatically add links to each pull request to facilitate the review process.

GitHub and CodeSandbox Integration

Open in Web Editor

This link opens the branch in the CodeSandbox web editor. Because the branch is a shared environment, you will be able to see any running previews, tests, or other DevTools that the PR author left open to assist with the review process.

Open in VS Code Extension

If VS Code (or VS Code Insiders) is your preferred development environment, you can open the branch directly from this link using remote-ssh.

Open Preview(s)

These links will take you directly to a preview environment — or a standalone devtool of a running preview task — depending on your task configuration.

Deployments

For projects with preview tasks configured, CodeSandbox can add Deployments to GitHub for easy access to running previews. These deployments provide easy access for individuals, as well as programmatic access for CI tasks using the GitHub API. Look for entries like the following:

{
    // Deployment fields...
    "environment": "CodeSandbox (Task Name)",
    "payload": {
        "provider": "CodeSandbox",
        "codesandbox": {
            "preview_url": "...",
            "shortid": "...",
            "task": "..."
        }
    }
}

Don't worry if you have other services creating deployments for your project; CodeSandbox will only manage deployments with "provider": "CodeSandbox" in the payload. For more complicated projects, CodeSandbox will create one deployment for each task configured with a preview.

Make sure to configure the preview field in your tasks for them to show up in the deployments.

Installing the GitHub App

Installing GitHub Apps

The GitHub App can be installed by...

  • An individual user, for some or all of the repositories owned by that user
  • An organization admin, for some or all of the repositories in that organization
  • A repository admin, for that specific repository

However, it is possible to request the installation of a GitHub App in repositories where you don't have the necessary permissions. Organization owners and repository admins will receive a notification on GitHub and via email asking them to approve or deny the request. Alternatively, you can configure the App through its official GitHub App Page.

Privacy and Permissions

The GitHub App allows CodeSandbox to retrieve some information about your GitHub account and, in some circumstances, to make changes on GitHub on your behalf.

Users can select specific repositories or grant access to all repositories in an organization. This selection can be changed at any time in the GitHub Settings.

For more information, check out the GitHub App documentation.

FAQs

I approved a GitHub OAuth App when I created my CodeSandbox account. Why do I need another GitHub integration?

This GitHub App is different from the OAuth integration required by Sandboxes and Repositories. The OAuth integration allows CodeSandbox to import repositories from GitHub, while the GitHub App allows CodeSandbox to provide the features listed above.

Why is the GitHub App asking for additional permissions after I've already installed it?

Occasionally we need to modify the permissions of the GitHub App in order to support new features. GitHub requires users to approve the new permissions before they take effect. Following are some additional details about changes we've made:

  • 31 August 2022: Added deployments permission in order to add a deployment to the GitHub UI for each preview task. This feature will only be active if (1) branch deployments are enabled for the project, and (2) task previews are configured in .codesandbox/tasks.json.

You can review the App's permissions at any time by choosing Configure from the official GitHub App Page.