Skip to content

Latest commit

 

History

History
165 lines (131 loc) · 13.2 KB

Workshop-Instructions.md

File metadata and controls

165 lines (131 loc) · 13.2 KB

GitHub for Managers - Workshop Instructions

The goal of this workshop is to demonstrate how to get started with some of the most important features in a GitHub repository, with a focus on the GitHub Flow. Links to descriptions of GitHub terminology are included in the steps below.

Table of Contents:

Concepts

Let's spend a brief moment going over some terminology. Links are provided to learn more about the concept.

Every repository contains administrative settings for you to manage your project effectively, including (but not limited to) visibility, collaboration and quality checking. Check out each of the settings to learn how you can find tune your environment.

Create an Issue

Let's create a tracking Issue to record our first item of work, which will be to create a file with your name.

  1. In the repository's Issues tab, click New issue. 📷
  2. Enter a Title indicating you will create a file with your name on it 📷. Example: 
    Create a new file - John
  3. In the Body of the Issue, let's add a Description similar to the following 📷: 
    I need to create a new file with my name.
  4. Click Submit new issue. 📷

Add your file and create Pull Request

Let's propose a file change to the repository to create a Pull Request:

  1. In the repository's Code tab, navigate to the workshop-attendees folder. 📷
  2. While in the workshop-attendees folder, click Create new file. 📷
  3. On the Create new file screen, be sure to provide a new filename. 📷
  4. In the Edit new file box, type some info about yourself, for example 📷: 
    Hello! My name is John.
  5. Scroll down to the Propose new file section and provide a commit message. 📷 Example: 
    Adding my file
  6. Click Propose new file. 📷
  7. The next screen will show the creation of the Pull Request, with some info about the specifics of your proposed change. Click Create pull request. 📷 A Pull Request will be opened for this proposed change.
  8. You may be presented with a body of text where you can add and remove as you see necessary. This is where you tell the repository owner a bit more about your change. If asked, click Create pull request. 📷
  9. Demo. The instructor will demonstrate traceability and tracking aspects, including:
    • Linking to Issues
    • Code Review
    • Assignment
    • Label(s)
    • Milestone
    • Project Visualization 📷

Now, a pipeline

GitHub concepts are well documented features, but I believe it is important to understand how developers do their work. Even new users to GitHub can set up a CI/CD development pipeline with little effort, let's give it a try now.

To practice creating a pipeline, let's set up our own personal workspace. To create our workspace we will fork the github-for-managers repository. A fork is effectively a copy of a project you can use to freely experiment without affecting the original project.

  1. Navigate to the workshop repository at https://github.com/universeworkshops/github-for-managers.
  2. In the top-right-hand corner, click Fork 📷. If asked, fork to your personal GitHub account.
  3. You will then be taken to your forked repository where you can experiment. Notice the forked from... message in the top-left, and notice you can now see a Settings tab because you are the admin here. 📷
  4. Let's protect the master branch. Click the repository's Settings tab, then Branches. Under Protected branches click the dropdown and select master. 📷
  5. In the Branch protection for master page, check all available settings. 📷

Setup CI

Let's set up a CI job for your repository. This will give us an automated build and test step when we propose a change.

  1. Open a new tab, go to https://circleci.com and click Log In. 📷
  2. Click Sign in with GitHub 📷, and then click Authorize circleci 📷.
  3. After authorization, you can access the CircleCI app at https://circleci.com/dashboard.
    • Note: If you are already a member of multiple GitHub orgs, you need to select your username in the dropdown at the top of the page. 📷
  4. On the left side, click Projects and then click Add Project. 📷
  5. Next to github-for-managers, click Setup project 📷, then:
    • For Operating System, select Linux 📷
    • For Platform, select 1.0 📷
    • Click Start building 📷
  6. After up to four minutes, your CircleCI tests should pass 🎉 🎉. 📷
  7. Check out the new Webhook created in your GitHub repository. Go to the repository's Settings tab, then select Webhooks to see that it was automatically created when you authorized it. 📷

Post-workshop exercise: Try setting up a Travis CI status check on your forked repository at https://travis-ci.org.

Setup CD

So our tests are wired in with CircleCI, now how do you deploy before merge? This helps us perform a better code review, we can see our actual application deployment before merging to master. Let's try it out!

First, let's connect Heroku to GitHub:

  1. Open a new tab, go to the Heroku dashboard at https://dashboard.heroku.com and Log In. 📷 📷
    • If you haven't yet, register for a new Heroku account. You will be sent a confirmation email. 📷
  2. Click New > Create new app. 📷
  3. For the App name, enter my-awesome-book-app-GITHUB_USERNAME. Heroku app names must be unique so append -GITHUB_USERNAME to the name. 📷
  4. Click Add to pipeline, then select Create new pipeline. Leave the defaults and click Create app. 📷
  5. In the Heroku Deploy tab, for the Deployment method select :octocat: GitHub and Connect to GitHub. 📷 Log in if prompted, but it should take your already logged-in session, where you can click Authorize heroku. 📷
  6. After authenticating Heroku to GitHub, type github-for-managers in the text box and click Search. Our repository should be displayed, then click Connect. 📷

Now, let's enable Heroku Review Apps. When a Pull Request is opened, each new commit can trigger automatic test deployments in an isolated environment, called Review Apps in Heroku:

  1. Go to the Heroku dashboard at https://dashboard.heroku.com. Select my-awesome-book-app-GITHUB_USERNAME. 📷
  2. Click Enable Review Apps 📷, then select both options:
    • ☑️ Select Create new review apps for new pull requests automatically 📷
    • ☑️ Select Destroy stale review apps automatically 📷
    • Click Enable 📷

End-to-End Test

Now we have CI/CD setup for our app. Let's try it out!

  1. Navigate back to your GitHub repository fork and select the Code tab. 📷
  2. Go to the file app/models/book.rb and click the ✏️ pencil icon to edit it. 📷 📷
  3. On Line 3, uncomment the line by deleting the # character at the beginning. 📷 📷
  4. Scroll down to the Commit changes section. Add a commit message, using the following as an example: 📷 
    Adding new test for the app
  5. In the Create a new branch... option, enter a new branch name, using the following as an example: 📷 
    add-test
  6. Click Commit changes 📷. A Pull Request will automatically be opened for this proposed change.
  7. Add the enhancement label and click Create pull request. 📷
  8. The Pull Request will now show the creation of a conversation about the change as well as the integrated dev tools you can follow throughout the requested change. 📷
    • Code Owner enforcement with automatic Code Review
    • Conversation
    • Initial and subsequent commits to this branch
    • Automatic build/test with link
    • Automatic staging deployment with link
  9. Browse the links in the Pull Request to see additional detail about your change and the checks it triggers.
    • One of the deployment links in the thread will link to an actual deployment of the MyAwesomeBookApp application. 📷 📷
    • Another link to show you the status of the CircleCI build/testing. 📷 📷