Register the GitHub App
GitHub Learning Lab is a GitHub App built with Probot. GitHub Apps are a special kind of integration that interacts with GitHub, and they require an active presence on the GitHub Enterprise instance. They do not consume a licensed seat, and are their own actor.
Creating the GitHub App
The GitHub App must be owned by a user or an organization; we recommend creating a new organization for Learning Lab, as it will be useful for other things (like creating courses). After your organization is ready, navigate to your-github.com/organizations/your-org/settings/apps/new.
- GitHub App name: We suggest "Learning Lab."
- Description: Feel free to use this Gist as a template.
- Homepage URL: The URL to your internal running Learning Lab instance, previously referred to as
APP_URL - User authorization callback URL: The URL to your Learning Lab, plus
/login/github/cb. - Setup URL: You should set this to the same as Homepage URL.
- Webhook URL: The same as Homepage URL.
- Webhook secret: Can be anything, though we recommend creating a new sha256 string. Be sure to note this down for later. Ensure no special characters or spaces are copied as the Webhook secret will be used across multiple fields and must match exactly.
Permissions
The permissions required highly depend on each individual course, so we recommend enabling read/write for all permission groups, with the exception of pre-receive hooks.
Events
All available events must be enabled so that Learning Lab can properly track the activity of users in their courses. It will only act on and receive webhooks from repositories it has been installed on.
Installation targets
The GitHub App must allow installation on Any account so that it can create repositories for the user.
To verify that this setting is selected on an existing app, see Changing who can install your GitHub App.
Important credentials
In the Installation documentation, there are a few credentials that are generated by the GitHub App that you'll need to take note of: the App ID, a new private key, and the webhook secret. You can find those on the /organizations/your-org/settings/apps/github-learning-lab page after your app has been created.
Avatar
The avatar for GitHub Learning Lab will be displayed whenever a user is taking the course - it is the actor that explains to the user how to make progress. By default, you'll see an automatically-generated avatar. To ensure users know and trust GitHub Learning Lab, please replace this image with the official Learning Lab logo.
Download this avatar and follow the instructions at Creating custom badges for GitHub Apps.