Welcome to the getting started with Utrecht University GitHub organization page. A GitHub organization is a shared account where members can manage their projects using their personal GitHub account. The Utrecht University GitHub organization is meant for storing, managing and publishing research projects. Below you will find instructions for connecting to the organization and general usage instructions for the organization. See the bottom of the page for resources to get started with using Git for version control.
For best practices, see Best Practices for Git @UtrechtUniversity.
Membership of the Utrecht University GitHub organization, including access to internal repositories, is restricted to employees of Utrecht University (UU). Become a member using your existing personal GitHub account; if you do not have an account yet, please create one. During this process, you will have to authenticate for this GitHub organization using your Solis-id. Your Solis-id is merely used to verify your employee status; all commits and actions performed in GitHub will be attributed to your personal GitHub account. By using one GitHub account, your GitHub profile page (which can be used as your curriculum vitae) will not only show your contributions in repositories belonging to this GitHub organization, but contributions in different GitHub organizations or personal repositories as well.
- Create a personal GitHub account (not necessary if you already have a GitHub account)
- Login to your personal GitHub account
- Configure two-factor authentication for your GitHub account
See below how to retain direct access to your repositories after switching on 2FA. - Connect to the organization (one-time only)
- Authenticate using your Solis-id. This will make you a member of the organization and grants you permission to create repositories and teams.
- Go to https://github.com/UtrechtUniversity, consider making your UU membership public so people can find you and start working!
- (Optional) Setup (or authorize) SSH keys for single sign-on to keep direct access to all your GitHub repositories. This is done in your profile settings, under SSH and GPG keys (Configure SSO). More elaborate instructions can be found directly below.
To get initial access to the organization, follow the steps above.
⚠️ After turning on two-factor authentication for your personal GitHub account, you cannot connect to your remote repositories using HTTPS URLs in combination with your GitHub password anymore. You will need to configure an 'SSH key' or a 'Personal Access Token' instead. This is a one-time action. After that your interaction with GitHub will be as before.
Use an SSH key or a Personal Access Token to access your resources from the command line or from RStudio, see Using two-factor authentication with the command line. These keys have to be authorized to be used for the GitHub organization UtrechtUniversity. When using an SSH key, you will need to change remote URLs in your repositories from HTTPS to SSH format. When using a PAT, you can continue using HTTPS URLs. See the following instructions:
- SSH access
Creating an SSH key
Authorizing SSH key for usage in the UU organization
Change the remote URLs of any existing repositories from HTTPS to SSH - PAT access
Authorizing Personal Access Token for usage in the UU organization
Personal Access Token for RStudio and GitHub
Use this GitHub organization for research projects or other UU-related work. Do not use this organization for exercises or personal activities.
This GitHub organization is meant for managing source code. Using this GitHub organization is not recommended for storing datasets with personal or sensitive data (feel free to contact Research Data Management Support for advice). However, it may be used for version control of documents or small-sized non-sensitive datasets. For managing research data, make sure that you create a data management plan first and check the Storage finder and Tooladvisor for appropriate solutions.
Be aware of the general university's user regulations for ICT platforms, and security best practices for GitHub. If you are a Git novice, make sure to learn the basics of Git version control first in order to manage your projects properly. Typical dangers include publishing data that should not be published or publishing passwords. Make sure you learn how to tell Git which files should and should not be tracked, especially if you work with any kind of sensitive data. Finally, be aware that if you (or any of your collaborators) have authorized any third-party applications, these applications may be able to view data in your private repositories.
- Read the security best practices for more tips.
- The security (suitability) level for this GitHub organization can be found in the Service Description on Intranet.
- More about GitHub and GDPR compliance: GitHub Data Protection Agreement and GitHub Privacy Statement.
You can use GitHub Pages to promote research projects, for example, by publishing a project website. For design purposes, it is OK to use a UU logo. However, do not use any other design formats that relate to the university's corporate website (uu.nl)
Use repository names that are descriptive for the project. Don't use names that are in some way ambiguous, especially when they relate to law or policy (e.g. repository names containing "policy" or "terms"). We reserve the right to rename repositories with ambiguous names. When in doubt, contact us.
Be sure to add a license to your work, since the license defines the rules for people who want to use your code/software. If you reuse licensed software, make sure that the license you choose is compatible with the license of the reused software. Choosing a license.
- Contact Research Data Management Support for questions regarding code and software licensing.
- Contact the Copyright Information Office if you have other questions regarding working with copyrighted contents.
As soon as you have authenticated with your Solis-id using the steps outlined above, you are granted permission to create repositories in the Utrecht University GitHub organization. View GitHub documentation for instructions on how to create a repository.
Create teams to organize your team or project repositories. As soon as you have authenticated with your Solis-id using the steps outlined above, you will be able to create teams in the Utrecht University GitHub organization. View GitHub documentation for instructions on how to create a team. More info about managing your team in the UU GitHub Organization
When you create a repository or team, you will automatically have permission to invite collaborators. When you invite a colleague to a team, they will automatically receive an invitation to join the Utrecht University GitHub organization. When you want to invite a colleague to a repository without using GitHub teams, the colleague should first become a member of the GitHub organization via the Getting Started steps above. If your colleague is a member, you can invite your colleague to collaborate on repositories.
You can invite non-UU collaborators or students by adding them as external collaborator to repositories: see GitHub documentation. Be responsible on inviting outside collaborators; only invite them to repositories they need access to.
Migrate a repository to the Utrecht University GitHub organization by mirroring the repository.
⚠️ Do not use the "Transfer ownership" option in your repository settings to transfer a repository to this GitHub organization. You will lose admin rights for the repository.
GitHub Actions minutes and storage are unlimited for public repositories. Whenever possible, use public repositories if you are using GitHub Actions. There are monthly limits for using GitHub actions in private repos on an organization level. As soon as this limit has been reached, GitHub action minutes will be disabled for private repositories for the remaining part of the month.
The following applications are approved for usage in this GitHub organization:
- Zenodo
- Codecov
- Microsoft Teams
- Slack
- Travis CI
- GitHub Desktop
- AllContributors
Activation of these applications for your repositories differs per application: view instructions.
Submit an issue if you would like to use a new application.
Using Git version control is key in the Open Science paradigm and helps managing versions of files, collaboration and publication. A Git novice should invest some time to get familiar with the way of working. A one-day course will get you started.
Resources:
- Introduction to Git and GitHub using GitHub Desktop (by the Geo Data team)
- Introduction to Git and GitHub using command line (by Software Carpentries)
- Introduction to the GitHub Webinterface
- GitHub Skills
- Managing your team on UU GitHub
Courses:
We are very happy with any suggestions or contributions to improve the contents. The aim of this Repository is to help UU employees getting started with the Utrecht University GitHub organization. Read the contributing guidelines.
The content in this repository is licensed under the Creative Commons Zero 1.0 (release to the public domain).
Do you need help or have any other requests? Submit an issue or send an email: its.ris@uu.nl