A few days ago, we announced the launch of the ITOpsTalk repository on GitHub. This repo will feature Infrastructure samples for anything related to Azure Infrastructure, Hybrid, Windows Server, Containers, etc.
While the repository will be maintained by the Moder Infrastructure Cloud Advocates at Microsoft, you can also contribute with IT/Ops related samples by submitting a Pull Request (PR)! This blog post will cover how that process works, in case you are not familiar with using GitHub.
Fork the ITOpsTalk repo
The first step to contribute to the repo is to fork it to your own account. This is necessary as only Cloud Advocates have writing access to this repo. When you fork a GitHub repo, you create a clone of that repo under your own user. The nice thing about it, is that the repo knows it has a source and compares the two repos – If your forked repo is behind/outdated, you can sync it so the content will match. If you made changes to the forked repo in your account, you could then open a PR to merge your edits with our repo.
Before anything, if you don’t have a GitHub account, go create one. Once you have an account, make sure you are looged into it, then click the Fork button on the top right corner of the ITOpsTalk repo:
Notice the Owner on the image above should be you. Click Create fork. When the process completes, it will take you to your own version of the repo in your account:
A few things to notice:
- On the top left, you’ll see that the repo is now under your account, but it clearly shows that this is forked from the Microsoft/ITOpsTalk.
- It also informs you if your repo is behind (outdated) or ahead (you made changes to your fork) of the original repo.
- If you are ahead, you can open a PR to contribute your changes to the original repo. If you are behind, you can click the Sync fork option.
Making contributions to the ITOpsTalk repo
There are multiple ways to make edits/contributions to the repo, ranging from the most simple, to the more complex ones. Here we will cover two scenarios: Making changes to the repo via GitHub Desktop or using Visual Studio Code on your machine.
Contribute using GitHub Desktop
GitHub Desktop is a GUI app from GitHub that helps you manage the sync and other actions between repos and its copy on your machine. This tool is a great option when you are not going to make code changes to existing scripts, like when you have a finished script and you just want to offer it to the ITOpsTalk repo.
To get started, download the tool, then open and log into it. Once you have GitHub Desktop set up on your machine, go back to the GitHub webpage with your account and forked repo, click the Code button and select Open with GitHub Desktop. This will launch the GitHub Desktop app, and present you with the option to clone the repo on your machine:
Make sure you are cloning the repo to a folder on your machine that has enough disk space, as well as doesn’t have another folder with the same name structure. For example, if you cloned the original repo to C:\repos, you already have a folder with name ITOpsTalk in there.
Next, GitHub desktop will ask how do you plan to use the fork. This is because you could clone the original repo, but you’d have to create a fork later if you made changes and want to open a PR. We just anticipated that and created our fork already. With that, select the option to use For my own purposes. Later we will cover how to open the PR from your fork to the original repo.
From GitHub Desktop, you can also open a PR (if you’re ahead) or sync (if you’re behind). For now, let’s talk about how you make a contribution.
In this example, we will use a fictitious PowerShell script – PS1 file – to exemplify how you can contribute to the repo. In this case, all we have to do is to create a new folder on the structure of the repo:
A few things to notice here:
- The folder I’m using (as you can note from the header) is the one we cloned in the previous step.
- I created a new folder in the ITOpsTalk repo called “sample_abc”. It’s important that you use a name for the folder that doesn’t exist yet, and is descriptive enough for anyone else looking at the samples.
- I copied the PS1 file from wherever it was before to this new folder. I’m simply sharing this script with the repo, so all I have to do is to copy it.
- I also created a readme.md file in this folder. The readme.md file is important and you should add to it the description of what your sample script is, what it does, and how to use it. MD files represent Markdown, which are very easy to write. You can use a readme.md file from another folder as an example. When a readme.md file is present with the correct content, someone navigating the folder structure on GitHub can read it in the browser.
Now that I have my sample in the folder, I can go back to GitHub Desktop:
You will see the changes you made (files) listed on the left panel. On the bottom left, provide a summary/name for your commit. This will help us identify what are you proposing in this change. Click the Commit to main button. Now you will see an option to Push this change to your forked repo:
Click the Push Origin button. Once this is complete, your forked repo will be ahead of the original repo from Microsoft:
Click the Contribute button and then click Open pull request:
On the Open pull request page, you can check the information about the repos being used. Notice the base repo is the Microsoft one, and the head repo is your forked repo. Please provide a meaningful name to your PR, a description that will help us understand what you are proposing, and click Create pull request. Note: Please do not uncheck the “Allow edits by maintainers” as we might need to change a few things to get your PR approved.
A new PR will be open and the Cloud Advocates team will review it. Once approved, your sample will be listed in our public repo and your name will be listed as one of the contributors!
Contribute using Visual Studio Code
VC Code is a great option to use when you want to contribute by changing existing samples, or if you still want to work on the sample you are going to submit. Part of the process of using VC Code is similar to the instructions above: You need to fork the repo to your account and clone the forked repo to your machine. You can use the same instructions above to achieve that. Once you have cloned the forked repo to your machine, you can open VS Code and target the ITOpsTalk folder. Note: You might be required to trust the author of the repo to enable editing.
With VS Code open on the ITOpsTalk folder, you can visualize all the folder structure as well as all files. From here you can edit anything you’d like, be it a PowerShell script, a Bicep template, or even the description in a readme.md file.
Just like the previous section, you can also add new files to contribute to the repo. Simply copy the files to the folder structure (or create new files and folders):
Once you make changes to the folder and save them, you’ll see that the Source Control icon on the left panel shows a new count of changes. In our case, we made two changes, so the Source Control shows that. Click the Source Control button on the left side:
Notice the process here is similar to what we did with GitHub Desktop – you need to enter a Commit message (Summary), and click Commit. Once you do that, you’re back to the same stage as with GitHub Desktop: You can open a new PR to the original repo from Microsoft!
Conclusion
While not intuitive for IT/Ops people, using GitHub for collaborating on repositories is very simple. You can use different tools, but the process will be mostly the same. We covered how to use GitHub Desktop or Visual Studio code to make contributions to the ITOpsTalk repo – so don’t wait! Send us your samples and get your name featured in our repo!