If you’re new to GitHub and open source in general, figuring out how to get set up can be a challenge. This guide is for getting started with GitHub, and specifically targets LLNL developers working in the LLNL GitHub organization.
Setting up your GitHub Account
If you’re new to GitHub, you may want to read through the GitHub Help pages on Setting up and managing your GitHub profile. Here are some of the highlights:
Create an account on GitHub
Update your profile information
- Photo: A headshot photo, or image that is uniquely you.
- Name: Your first and last name.
- Bio: Include a few words about yourself! Don’t forget to mention @LLNL.
- URL: This might be your https://people.llnl.gov page, or a personal website if you prefer.
- Company: Probably
Lawrence Livermore National Laboratory, @LLNL.
- Location: Your primary location.
@LLNL email address (and any aliases) to your Email Settings page.
Enable Two-factor authentication
- Membership in the @LLNL GitHub organization will soon require that 2FA has been enabled on your GitHub account
- There are several options for configuring 2FA for your GitHub account:
- YubiKey hardware security keys
- Note that the YubiKey deployment (called “MyPass” at LLNL) is in its pilot phase, and not all users have them yet.
- YubiKeys are the preferred 2FA option, due to the security of the YubiKey hardware tokens. If you have been issued your LLNL YubiKeys they are highly recommended for securing your GitHub (and other) accounts which support them.
- Google Authenticator
- Google Authenticator is a mobile application which you can install on your personal or government issued phone.
- It allows provides a one time token (OTP) which you can use to authenticate to GitHub.com
- Authy is a desktop (or laptop) based application which can be used to generate a one time token (OTP) for use logging in to GitHub.com.
- This option is usually best for when you do all or most of your work in an environment where you do not have access to a mobile phone or USB YubiKey.
- You will also have the option during 2FA to generate and save a list of recovery codes to get into your account in the event you lose access to one of your 2FA methods. This is highly recommended, and the recovery codes should be stored someplace safe. Some options for storing your recovery codes include:
- Printing the codes and storing them in a safe place in your office.
- Storing the recovery codes in a password manager that you might be using.
- It is recommended that you set up MULTIPLE 2FA options. This can protect your access to account in the even that you lose access to one of your authenticators.
- For more information, check out the Two-factor Authentication post on the GitHub Blog.
- Having trouble setting up 2FA? Contact the LLNL GitHub Admins who may be able to help.
Joining the Organization
If you are an employee at LLNL, and have 2FA enabled, congratulations, you are eligible to join the LLNL GitHub organization!
Send an email, with your GitHub username included, to email@example.com from your
@llnl.gov email, requesting to be added to the organization.
After an administrator has added you to the organization, you will receive a notification email from GitHub.
- Alternatively, once the invitation has been sent, you will see a notification banner at the top of https://github.com/llnl which you can use to accept the invitation.
Head over to the @LLNL People page and make your membership
Review the “Working with LLNL Repositories” information below.
Welcome to the organization!
Working with LLNL Repositories
Repositories within the LLNL organization are owned and managed by LLNL. Please do not create personal repositories here.
Reminder, that all information produced by LLNL must follow the guidance set forth by the LLNL Information Management (IM) Policy.
Before content is placed into an LLNL GitHub.com repository it should be reviewed and released via the Information Management (IM) process. Once released, an appropriate open source license and
LLNL-CODE- release number should be provided and included in the repository.
Remember that these repositories are hosted on GitHub servers, NOT LLNL servers, and content placed in them should be limited to “email like” communications. That means:
- NO Classified
- NO Export Controlled
- NO Official Use Only (OUO)
- NO Health Insurance Portability and Accountability Act (HIPAA)
- NO Personally Identifiable Information (PII)
- NO NDA or vendor-proprietary information
- NO Unclassified Controlled Information (UCI)
- NO Unclassified Controlled Nuclear Information (UCNI)
When in doubt, contact a Derivative Classifier (DC) and / or Information Management (IM) for further guidance.
Now that your project is on GitHub, make sure users and contributors can find it! There are several ways to do this. Contact firstname.lastname@example.org for help with the following tasks:
- Include meaningful metadata (description and topic tags) in your repository. Example: Spack lists several topic tags below a one-sentence description.
- See helpful hints on GitHub’s topic help page. Add tags relevant to your project’s programming language, platforms, and more (e.g., Python, HPC, Linux).
- Include a summary of your project with GitHub and documentation links on LLNL’s Computation website.
- Let Twitter followers know your project is available on GitHub.
- Publicize any outreach activities related to your project. Examples: You have a paper/poster/presentation accepted at a conference; you’re hosting a workshop or webinar; your project is nominated for an award; or you’re speaking on a podcast or guest blogging.
There are many great “getting started” guides for GitHub, here are a few that we recommend if you’re looking for more information:
The Federal government also provides some relevant information: