GIT: Using GitHub repositories

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.

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.

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:

• Installing Git
• Installing GitHub CLI (not GitHub Desktop)

Once the environment is installed, you will need to configure it using our standard instructions to prevent issues down the line.

• Set up the GitHub credential helper in the ~/.gitconfig file
• Authenticate with GitHub using the gh auth login command (answers to prompts in documentation)
• Join the University of St. Thomas GitHub Organization (optional)

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. 

1. In a GitHub repository, click Code, then under Clone, copy the HTTPS link.
2. 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:

1. Escape/Cancel out of any login prompt and ensure you logged in successfully using the gh auth login command.
2. 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.)
3. 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.

• Development Environment: Getting Started
• GIT: Git Essentials at St. Thomas
• St. Thomas GitHub Campus