This guide outlines two common scenarios for integrating your GitHub account with Bunnyshell, catering to varying ownership situations. Screenshots provide step-by-step visual assistance for a smooth integration experience.

Integration

Scenario 1: You are the Organization Owner

Step 1: Access the Integration Section

Access the Bunnyshell platform and navigate to the Integrations section, under Git Integrations, select GitHub.

Step 2: Choose Account or Organisation

Choose your GitHub account or your organisation. If your account is already connected, you can configure the existing integration.

📘
You can also configure the existing integration from Bunnyshell Integrations -> Git repositories.

Step 3: Define Integration Scope

Define the scope of integration: grant permissions to all repositories or select specific repositories for synchronisation.

Click the Install and Authorize button to finalise the integration and you will be redirected to the Git Integrations page where you will see all your integrations.

Scenario 2: You are a Member of an Organization

Follow the steps outlined in Scenario 1 up to the point of granting permissions. At step 3 you will request authorisation upon which the account owner will receive an email to authorise the request.

Step 1: Account Owner Receives Email

The GitHub repository account owner will receive an email with a permission link. Upon clicking the link, they will be directed to grant the required permissions.

After granting the permission they will be redirected to a Bunnyshell page that provides them with an installation ID which they must pass back to the person who requested authorisation.

Step 2: Finalise Integration

As the requester, upon receiving the installation ID, navigate to Bunnyshell Integrations page and click on finalise installation and paste the received installation ID into the "Finish Installation" dialogue as illustrated below:

By following these instructions, you can successfully integrate your GitHub Repository/Account with Bunnyshell.

These scenarios accommodate different roles within the repository, ensuring a secure and efficient integration process that aligns with your collaboration needs.

Revoking access for Bunnyshell Github App

In order to revoke the Bunnyshell Github App access to your account follow these steps:

Step 1:

Remove the integration from the Git Integrations page.

Step 2:

Go to your Github account and navigate to the profile settings by clicking on the profile picture in the top left and selecting settings from the list.

Step 3:

Navigate to the application in the sidebar (1), select the Authorized Github App tab (2) and click on revoke (3).

And under the Installed Github Apps, configure the Bunnyshell app and Uninstall it.

You have now revoked access to Bunnyshell.

GitHub App Permissions

Bunnyshell requires the following GitHub App permissions:

Repository permissions
- Contents - Read-only -> Repository contents, commits, branches, downloads, releases, and merges. - This is mandatory to accept, it allows Bunnyshell to clone the code, list branches and commits.
- Issues - Read-only -> Issues and related comments, assignees, labels, and milestones. - This is optional, but it allows Bunnyshell to read the comments on a PullRequest in order to implement the Git ChatOps feature.
- Metadata - Read-only -> Search repositories, list collaborators, and access repository metadata. - This permission is mandatory for all GitHub applications that access repository information.
- Pull requests - Read and write -> Pull requests and related comments, assignees, labels, milestones, and merges. - This permission is mandatory to accept, it allows Bunnyshell to read PR details and to comment in PR with the ephemeral environment deployment status.
Organization permissions
- Members - Read-only -> Organization members and teams. - This permission is mandatory to accept, it allows Bunnyshell to check if a GitHub user is member of a GitHub organization, see above Scenario2
Account permissions
- Email addresses - Read-only -> Manage a user's email addresses. - This permission is mandatory to accept, it allows Bunnyshell to create a Bunnyshell account with the GitHub profile's primary email when the user first installs the GitHub App from GitHub marketplace.

The GitHub App is also configured to Request user authorization (OAuth) during installation, so it can check the identity of the GitHub user that performs the installation, to either create Bunnyshell account or check the membership in a GitHub organization.

GitHub App Permissions request timeline

31 July 2023 - requested Organization permissions -> Members - Read-only
08 Feb 2024 - requested Repository permissions -> Issues - Read-only
01 Aug 2024 - requested Account permissions -> Email addresses - Read-only