GitHub repositories can be used for code and script examples, classes, collaboration, and version control of text based information. Many features make GitHub a perfect solution for offering documentation of scripts, code, and tutorials.
- Formatted code blocks: Markdown syntax supports language-specific code blocks, which display and highlight code correctly. This makes explanations clearer and easier to read, as the code is formatted just as it would be in an editor.
- Visual graphs: Repository graphs offer a visual representation of a project's functions and their relationships, which can be invaluable for explaining the flow and architecture of a codebase.
- Code navigation: GitHub's code navigation features let you jump to function definitions and find all references to a symbol within a repository. This functionality is crucial for understanding how different parts of a codebase connect and interact.
- Wikis: For more extensive, long-form documentation, each repository can have a Wiki. This feature is better suited for creating structured, navigable guides, manuals, and detailed feature breakdowns, which can be edited and maintained by collaborators.
- GitHub Pages: You can use GitHub Pages to publish a static website directly from your repository, providing a professional-looking, standalone documentation site for your project. This is ideal for detailed API references or user guides that require more separation from the codebase.
Note: Critical university infrastructure, enterprise applications, and projects deployed to AWS should use
AWS CodeCommit. However, due to the features mentioned above, GitHub can be used as a repository for supplemental documentation.
Accessing GitHub
The university provides GitHub Campus access for staff and faculty to support collaboration. Any university member with a current login can join by logging in to their existing personal GitHub account and then using the SSO Connection link to gain access. You will retain your personal GitHub account and will now have access to the St. Thomas repositories. Review the documentation for GitHub Campus for more information.
A benefit of the St. Thomas GitHub Campus is that you can grant access based on university user groups and contacts without making your repository publicly available.
Even without utilizing St. Thomas GitHub Campus, you can still clone and access repositories from your own account or any account you have access to.
Note: Whether you plan to access St. Thomas GitHub Campus repositories or your own personal repositories, the method for setting up credentials and cloning repositories is the same; follow the directions below.
Accessing and Cloning a Repository
We have a standard set of instructions for installing development environments on Mac, Windows, Linux, or in virtual environments (such as UTM and WSL). Using the standard environment configuration saves time and headaches and allows us to quickly support, troubleshoot, and resolve any configuration issues you may have.
You will need to follow our development environment installation documentation for:
Once the environment is installed, you will need to configure it using our standard instructions to prevent issues down the line.
Our method does not use GitHub Desktop (which can pose issues) and does not require creating tokens or credentials, which are considered an outdated and insecure method. Instead, we rely on the GitHub CLI and gh auth login. It is much simpler, reliable, and more secure.
After your environment is configured (again, be sure to follow the GitHub configuration instructions!), you are ready to clone the repository.
- In a GitHub repository, click Code, then under Clone, copy the HTTPS link.
- Change to the directory you will clone the repository into (typically
~/projects/personal/github or ~/projects/ust/github) and execute the command:
git clone <the-url-you-copied>
Troubleshooting
If you are prompted to log in or receive a 403 or repository not found error:
- Escape/Cancel out of any login prompt and ensure you logged in successfully using the
gh auth login command.
- Double-check your configuration. A typo, incorrect directory path, or not following the configuration documentation is the problem 99.99% of the time. (Actually, in all the tickets we've received, this has been the issue 100% of the time.)
- If, after reviewing the documentation, you still have issues, please reach out to us via the Request Service link on the Developer and Cloud Tools page. It is still most likely a typo in your
.gitconfig such as a path or credential helper, but, just like in coding, sometimes a second set of eyes can spot the issue quickly.
Additional Resources
The Developer and Cloud Tools page offers abundant resources to get you started in all aspects of coding, scripting, and development. If you require assistance, please use the Request Service link.