Starting in 2018, with the help of Jeff Rouse (@JeffRoSQL) John Morehouse (@SqlrUs), and Chris Yates (@YatesSQL), I took over as a member of the leadership team for the Louisville SQL Server and Power BI User Group (LSUG). LSUG has been an active local chapter of Pass for the last decade with a current member count of 690 members. When we first started working with the administrative side of the chapter, we quickly realized how much effort it took to set up a meeting each month. We had decent support from the community as far as venue locations to hold the meetings, and an amazing sponsor (TekSystems). However, trying to find active speakers within the community, without burning out our local speaker group has been rather difficult. On top of that, the process once we found a speaker was rather cumbersome for both us and the speaker. We didn’t have a dedicated communication platform (Email, Twitter, LinkedIn, etc) and the majority was routed through on a member of the team causing a lot of info to be relayed.
So a couple months had passed and I was prepping for my session on Introduction to GitHub at LSUG. The initial session was just your base layer Intro course. But as a began to build out the demos, I started to think about how we could leverage GitHub repos to manage some of the administrative tasks within the group. For this to be beneficial it has to solve the below items.
- Easy to use for Speakers and Members of the User Group
- Notifications to the leadership team when items changed
- Survive additional leadership changes
- Security, Security, Security!
The first item is pretty simple if the tool isn’t easy to use then people will not use it. To help combat this, a descriptive readme document needed to be created so that when you first accessed the repo you knew how to use it. The second item was to help with the constant communication between the leadership group. We’d route the notifications of new issues or commits to a slack channel we were using to communicate for the admin group already. This would ensure that we could all take vacations throughout the year without worrying if we would need to watch our phones. The third item is something that was important to me. I wanted to build something out that if the day came that I no longer had the capacity to help lead the group, someone else could jump in easily and begin working with the tools effectively. Lastly, Security! This like any other Open Source repo would allow outside entities to access and manipulate the object stores. We had to make sure that any changes being pushed to the repo were reviewed and only approved by set parties within the leadership group.
As the article continues, I will overview the steps I took to build this out initially and hopefully give you the steps to recreate if you feel this is beneficial to your group.
Setting up the Organization
What is an Organization? An Organization in regards to GitHub is a way of grouping projects in a shared account so that collaborators can work on multiple projects at once within a business or an open source project. In the purpose of our group, we’d use an organization to group all the repos that would belong to the Local User group so that it made accessing the groups’ repo easier for the admins, it’s members and the speakers. To create an organization first login to your GitHub account. Once signed in using the switch context in the upper left corner of the page to create a new organization (example shown below).
Once selected, you will be prompted to fill out a couple of base layer items to create the organization.
- Organization Name
- Billing Email
- Project Type
- Organization Members
- What is the Organization for
- How long do you plan to use the Organization
- How many members do you expect
If you’d like additional info on organizations, please go here: About-Organizations
Setting Permissions for the Organization
When you add a new member to an Organization you have two roles that you can assign.
- Owner - Which has full administrative access to the entire organization.
- Member - Which can see every member and non-secret team in the organization, and can create new repos
Any visitor not defined as a member of the Organization will have public access to the Org and it’s repos only.
Creating Teams in GitHub
Teams are a way of grouping members in a way to help better communicate issues or limit permissions on a repo. Initially, all that we’ve created is a team to be used for the UG Admins. This way if communication is needed to the Admin group, all a member of the team will need to do is to use the @UG_Admins tag in an issue or discussion to send traffic to the group.
To create a team, selected the Teams menu item from the file menu under the organization.
Once selected, hit the New Team button at the lower right of the page. This will prompt you for some info required to create the team for your organization.
Once the team has been created we need to assign members to the team like we did the organization. To do so, select the member’s menu item in the top right of the screen. Select add member and search for the user that you’d like to add to the team and hit invite.
If you’d like additional info on organizations, please go here: About-Teams
Setting up the Repository
Next, we will create a repo to be used for Speakers. In regards to our group, we will use this repo for speakers to submit an issue for a session they’d like to present, members to submit an issue for sessions they’d like to see, and for the admins to manage work around the sessions using GitHub Projects. To create the repo, select new in the upper left corner of the page.
You will then be prompted to enter some info about the repo that you want to create.
- Owner (Make sure to select your new Organization)
- Repository name
- Description (Be concise yet descriptive!)
Then there are a couple of items we need to select. You should always initialize a repo with a README file and then we should add a license to the project is it’s going to be accessed by outside parties. In this case we will select the MIT License. For some info on licensing with GitHub, please go here: About-Licensing
Once submitted your repo will be created and access will automatically be granted to any members of your organization.
If you’d like additional info on repositories, please go here: About-Repositories
As a general practice for me, I always create an additional dev branch off of the master once I create a new repo. This branch will what all contributors will compare and build their pull requests from. To create a new branch select the branch switch context and type in the branch name in the find or create branch textbox. Then select Create branch: Dev to initiate to issue the creation of the branch.
If you’d like additional info on branches, please go here: About-Branches
Protecting Your Branches
Now that we have a couple of branches within our Repo to work from, we need to add some protection around them so unattended changes are not pushed without approval from the admin group. To add branch protection to a repository, select the settings tab from the file menu strip within the repo.
Once at the next page, select the branch tab from the list on the left side of the page. From here we will add a new branch rule to the repo that will add some protection around the branch. To add a new rule, select the Add Rule button on the right side of the page.
Once on the next page, we will need to define a branch name pattern. This field accepts wildcards(*) if needed. In this case, we will create a rule for the master and dev branches created in the past exercise.
As a basic rule setting for this project, we will only enable the setting for requiring pull request reviews before merging.
If all done correctly, you should see your branch under Applies to _ branch like below.
Complete the above steps on any additional branches that you require.
If you’d like additional info on protecting branches, please go here: About-Protected-Branches
Creating Issue Templates
Issues are normally used within GitHub to request a new feature or to open a new bug against a project. In the case of this repo we will be using issues for speakers to submit a session that they’d like to present or for members of the group to request a session that they’d like to see. To create a new issue template, go to the settings tab of the file menus strip as we did in the above exercise. Once there, select the add template/Custom Template button in the middle of the page.
As discussed above, we will create one template to be used for speaker submission. An example of what we require to work submission is below.
Next, we will create another template to be used for members of the user group to request for a session to be found. This will allow us to vet the session and see what the turn out would be if we secured a speaker.
If you’d like additional info on issues within GitHub, please go here: About-Issues
Creating a Project in GitHub
GitHub projects are your basic kanban style board to be used to manage work from within the repo. There are a couple of different options here, as well as some third-party add-ons that could be used in replacement for to this. For the instance of this post and our current repo, we will be using the projects within Github.
To create a project select the projects tab from the file menu strip on the repo. Then we will need to select the new project button on the page so we can define out what the project will be used for.
In the next page, we will need to define out a title of the project, a concise but descriptive description and then the project template. We will be using the Template: Automated Kanban template that way as the cards progress throughout the board the issues will be updated with the changes.
Once the project has been created, you will be provided with a base kanban board with a couple of default columns. These can be adjusted to fit your needs but for this project, we will have 5 columns defined.
- Session Submitted (Initial entry point of all issues)
- In Review (Cards will be moved here during the review process to make sure we have everything required)
- Session Accepted (Cards will be moved here once the review has been completed and signed off by an admin)
- Scheduled (Cards will be moved here once the date and venue information has been secured)
- Session Completed (Cards will be moved here once the session has been completed at the User Group)
Once these have been adjusted, we can then add cards once new issues have been submitted. To do this, select the +Add Cards button in the top right section of the project page. This will default to any open issues in your repo. We can then drag the card to the Session Submitted column in the project.
By utilizing the projects within GitHub, we can define out a central location where work can be maintained. This will allow all members of the team to know where a session is as far as work and what items are still needed.
Setting Up Notifications
Notifications can be setup native to GitHub or you can use a third-party add-on like Slack to send notifications to a channel. This is all based on personal preference within your group.
If you’d like additional info on organizations, please go here: About-Notifications
In closing, using GitHub as a way to manage your group may not be for everyone and there are still many ways to improve upon what I have built so far. But what I’ve found so far from using it is that it solves some of the issues I initially stated within the introduction. My hope is that from this article, you can take some of these items and build out something that works for your group.