Repository and Project Setup

Note: The expectation is that the mentor will work with the mentee to accomplish this setup. Since almost everything is done within the mentee’s GitHub account, the mentor will largely be monitoring and helping the mentee with these instructions.

Set up your repository

  • Go to the repository template.
  • Click on “Use this template” (option “Create a new repository”)

    (Note: This button may not show up if your browser window is too narrow 🤷🏼‍♂️. Try expanding your window if you don’t see it).
  • When the “Create a new repository from [REPO NAME]” pop-up appears:
    • Select your gitHub account
    • Assign a repository name
    • Keep your new repo “Public”
    • Click the “Create repository from template” button
    • Go back to your “main” branch, and click the link to “Protect this branch”

    • Select “Require a pull request before merging”, “Require approvals”, “Dismiss stale pull request approvals when new commits are pushed” and “Require approval of the most recent reviewable push”. These changes will require you to work on issue specific branches and then submit a PR for mentor review in order to merge them to the main branch.

      Push the “Create” button.

      This discipline will help your mentor review your work, and mirrors the way many organizations will work.

Add your mentor as a collaborator

  • In you repo, select the “Settings” tab at the top
  • Select the “Collaborators” tab to the left
  • Click the “Add people” button
  • Use the search to find your mentor and select them as a collaborator
  • At this point, your mentor should receive an invite email and will show in your repo as “pending invite”
  • From the invite email the mentor can click the “View Invitation” button and accept the invite.

Set up your project

  • Go to the matching project.
  • Click on the ellipses on the right, and click “Make a copy”
  • When the “Make a Copy” pop-up appears:
    • Select “Draft issues will be copied if selected” (this is important, as all tasks are set up as “draft issues”)
    • Set your GitHub account as the “Owner” (you’ll probably want this to be the Mentee’s account)
    • Name the Project as you desire (I just removed the “[copy]” text)
    • Click the “Copy Project” button

Connect your project to your repo

  • Navigate to your new repo
  • click on the “Projects” tab.
  • Click on the “Link a Project” button
  • select the project you created to link the two
  • Be sure to make the project “public” so that your mentor can see it.
    • Select “Settings”
    • Under “Visibility” select “Public”

Grant the “Write” role to your mentor.

  • From the Project settings, click the “Manage Access” tab on the left
  • Find your mentor in the search box for “Invite collaborators”
  • Make sure the Role is “Write”
  • Click “Invite”
  • The mentor should receive an email to accept the invitation to collaborate

Set up workflow to change status to “done” when issue is closed

  • From the ellipsis button on your project, click “Workflows”
  • select the “Item closed” workflow, and click the pencil icon to edit.
  • from the “Set value” dropdown, select “Done”
  • click the “Save and turn on workflow” button

Set up workflow to change status when a pull request is merged

  • Follow the same process to setup and turn on the “Pull request merged” workflow.

(Optional) Configure a board project view for the mentee

  • You can add a new View of type “board”
  • If you add a “-no:status” filter and save your changes, the mentee’s board will not be flooded with tasks that have not yet been converted to issues.