How-To: Link GitHub Organization

Written By Envisage Support

Last updated 20 days ago

In order to link the desired GitHub Organization, users must use a GitHub Organization account, or have requested permission from an admin of that GitHub Organization.

Linking a GitHub organization to an Envisage organization allows for automatic linking between tasks and pull requests, provided the branch or pull request has been named appropriately. This enables the user to view all the pull requests related to a particular task.

Envisage Link Preparation:

  • In the header nav bar, navigate to ‘Organization’.

  • In the side nav bar, navigate to ‘GitHub’.

    • Click the ‘Connect GitHub’ button.

    • Clicking on ‘Connect GitHub’ will open GitHub in the same browser window with the following prompt.

      • If not signed in, sign in to GitHub via normal means.

      • Grant authorization to Envisage. Once authorization is complete, the browser will redirect back to Envisage.

  • Select the newly linked GitHub Organization via the dropdown modal, and click Submit.

    • Upon submitting, the GitHub app installation page will load in the browser

      • If the Github Organization is owned by the user, the following prompt will appear

        • Click Install to finish linking the Envisage Organization to the GitHub organization. The browser will redirect to Envisage upon completion.

      • If the GitHub Organization is not owned by the user, a prompt will appear to send a request from the owner to the organization.

        • Upon clicking Request, a request email will be sent to the owner of the organization:

        • Navigate to the linked GitHub page using the details included in the email.

          • Click Approve & Install to finish linking the Envisage Organization to the GitHub organization. The browser will redirect to Envisage upon completion.

  • In the header nav bar, navigate to ‘Projects’.

  • In the side nav bar, navigate to ‘GitHub’.

    • Click the ‘Map/Add Repository’ button.

    • Fill out the information in the following modal, and select the desired repositories.

  • In the header nav bar, navigate to ‘Tasks’.

    • Click on any task or create a new task and open it in the side panel.

    • Navigate to the Linked PRs tab, and note the GitHub branch name identifier at the top

      • the format for every GitHub identifier uses the following:

        • Project Name - Task ID

    • This identifier is used to name one of two things in the relevant GitHub organization:

      • Branch Name

      • Pull Request (PR) Name

GitHub Preparation & Link:

Method 1: Branch name

  • Create a branch with the GitHub branch name identifier as the name of the branch.

  • Commit code changes to that branch.

  • Create a pull request.

  • Return to the related task in Envisage, and refresh the table in Linked PRs to verify that the new link works as intended.

Method 2: Pull Request name

  • Within any branch under the connected repositories, create a pull request with the GitHub branch name identifier included anywhere in the title of the pull request.

  • Return to the related task in Envisage, and refresh the table in Linked PRs to verify that the new link works as intended.