These FAQs primarily target LLNL developers working in the LLNL GitHub organization. Don’t see your question listed below? Please contact LLNL GitHub admins. Please also refer to our Contributing Guidelines and Code of Conduct.

If you’re new to GitHub and open source in general, figuring out how to get set up can be a challenge. You may want to read through the GitHub Help pages on setting up and managing your GitHub profile.

1. Create an account on GitHub.

   You do not need a separate work account and personal account. Instead, you can link multiple email addresses to the same GitHub account, which is almost always preferred.

2. 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 people.llnl.gov page, or a personal website if you prefer.
   • Company: Lawrence Livermore National Laboratory, @LLNL.
   • Location: Your primary location.

3. Add your @LLNL email address (and any aliases) to your Email Settings page. This will link any commits done via your Git identity to your GitHub account.

4. Enable two-factor authentication (2FA).

   • Learn how to set up 2FA at the Lab .

Membership in the @LLNL GitHub organization requires that 2FA has been enabled on your GitHub account.

There are several options for configuring 2FA for your GitHub account:

YubiKey hardware security keys

• 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 YubiKey, it is highly recommended for securing your GitHub (and other) accounts which support them.
• Learn more about setting up your YubiKey with GitHub

Google Authenticator

• Google Authenticator is a mobile application which you can install on your personal or government issued phone.
• It provides a one-time token (OTP) which you can use to authenticate to GitHub.com
• Learn more about setting up Google Authenticator with GitHub

Authy

• 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.
• 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.
• Learn more about setting up Authy with GitHub.com

Additional 2FA info

• You 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. Saving your recovery codes 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.
• We recommend that you set up multiple 2FA options. This can protect your access to your account in the event that you lose access to one of your authenticators.

Get More Info on 2FA Contact the LLNL GitHub Admins

If you are an employee at LLNL and have 2FA enabled, you are eligible to join the LLNL GitHub organization and appear in the member list.

1. Send an email, with your GitHub username included, to the LLNL GitHub admins from your @llnl.gov email, requesting to be added to the organization.

2. 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 github.com/llnl which you can use to accept the invitation.

3. Head over to the @LLNL People page and make your membership Public.

Before content is placed into an LLNL GitHub.com repository, it should be reviewed and released via LLNL’s Information Management (IM) process. All information produced by LLNL must follow the guidance set forth by the LLNL IM policy for both initial release and incremental contributions .

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 information
• No export controlled information (ECI)
• No Health Insurance Portability and Accountability Act- (HIPAA-) related information
• No personally identifiable information (PII)
• No nondisclosure agreement or vendor-proprietary information
• No controlled unclassified information (CUI)
• No unclassified controlled nuclear information (UCNI)

When in doubt, contact a Derivative Classifier (DC) and/or IM for further guidance.

Make sure your repo contains community health files, including:

• An appropriate open source license and LLNL-CODE-xxxxxx release number. See the LLNL Software Licensing page for details and examples.
• A README file that summarizes what the software does and how others can use it.
• A NOTICE file that includes LLNL auspice and disclaimer statements.
• A CODE OF CONDUCT file that defines standards for how to engage in your project’s community.
• A CONTRIBUTING file that communicates how others should contribute to your repo.

After your project has been initially released on GitHub and you are ready to provide a new version, a good practice is to tag the version and include release notes.

Another good practice is to provide user documentation. Read the Docs (RtD) is a common platform for user guides, tutorials, quick start instructions, and other forms of documentation. Our LLNL/.github repo contains step-by-step instructions for setting up a RtD instance, a template you can start with, and links to various resources for tips and additional details.

Submit your repo to DOE CODE so others can find it when searching through DOE-funded projects. After your repo is included in DOE CODE, you may also want to add the digital object identifier (DOI) to the repo.

If your repo is research software, consider submitting it to the Journal of Open Source Software (JOSS). Submission will produce a citation to include in your README file, then users or other researchers can cite your software correctly.

The JOSS RtD site describes the submission requirements. JOSS defines research software as “software that solves complex modeling problems in a scientific context (physics, mathematics, biology, medicine, social science, neuroscience, engineering); supports the functioning of research instruments or the execution of research experiments; extracts knowledge from large data sets; offers a mathematical library; or similar.” (You can also become a reviewer, if you are so inclined.)

• Repositories within the LLNL organization are owned and managed by LLNL. Please do not create personal repositories here.
• All LLNL repos must go through the IM process (see the FAQ How do I get my repo reviewed and released for GitHub?) and display the appropriate open source license and LLNL-CODE-xxxxxx release number.
• If the repo wasn’t developed at LLNL, its license needs to be clearly indicated. See the LLNL Software Licensing page for examples.

If you’ve set up your repository within the LLNL organization, you don’t need to take any action; it will automatically appear after the next data update.

• If your repository exists under a different organization, you can move it to LLNL: Settings > Danger Zone > Transfer ownership > Transfer button. This process notifies our GitHub admins, who can update your role. For instance, upon transfer, repo admins are defaulted to the write role instead of admin. The transfer process also includes your project’s association with team members who contribute to the repo; they too come over with the write role by default.

• Alternatively, if you do not wish to transfer your repo, you can instead submit a pull request updating the input_lists.json file with your organization and/or repository names. List your organization under the "orgs" line only if you intend for all of its repositories to be included in the catalog (e.g., glvis); otherwise, list only the repository under the "repos" line within the context of your organization (e.g., hpc/spindle).

• If your repo is part of the RADIUSS project, be sure to add it to that website’s contributor-ci.yaml file.

If you have a project logo, please follow the Contributing Guidelines (see the question How do I change how a specific repo appears in the catalog?) for naming and uploading the file. If your repo is part of a non-LLNL organization that has its own avatar, that image will automatically display next to the repo name in the catalog, unless superseded by a repo-specific logo.

Please also tag your repo with this site’s catalog categories so it will show up in the filterable catalog. Follow the Contributing Guidelines (see the question How do I update or use the catalog categories?) for a list of tags.

Now that your project is on GitHub, make sure users and contributors can find it! There are several ways to do this. Contact open-source@llnl.gov if you need help.

1. Include meaningful metadata (description and topic tags) in your repository. Example: Spack lists several topic tags below a one-sentence description.

   • Start with our list of recommended, standardized topics, which are listed under the question How do I change how a specific repo appears in the catalog? in our Contributing Guidelines.

   • 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).

2. Let X/Twitter followers know your project is available on GitHub. Feel free to tag the @LLNL_OpenSource handle on your own tweet, or submit a request to open-source@llnl.gov so we can post on your behalf.

3. Publicize any outreach activities or major milestones related to your project such as:
   • A paper/poster/presentation is accepted at a conference
   • An upcoming workshop or webinar you’re hosting
   • Your project received an award nomination
   • You’re guest blogging or speaking on a podcast
4. Include a summary of your project with GitHub and documentation links on LLNL’s Computing website. Contact webmaster-comp@llnl.gov for this particular task.

Submit a pull request! This website is a GitHub repo just like any other LLNL open source project. News is housed in the _posts directory, and templates are found in the LLNL/.github repo. See Contributing Guidelines for more information.

Before contributing, please contact open-source@llnl.gov with your idea or if you have questions about whether your proposed content requires the LLNL review and release process.

Yes, you can give external contributors Write access to your GitHub repo. Anyone with Admin access to your repo can enable this: Settings > Collaborators > Manage access > Add people > enter their username and select.

If you don’t already have Admin access to your repo, contact github-admin@llnl.gov to request it.

1. Remove the specific topic tags (e.g., math-physics) that connect it to this website’s browsable categories.

2. Remove the repo from the RADIUSS contributor-ci.yaml file, if applicable.

3. Submit a pull request updating the input_lists.json file to remove your repo’s name.

4. Change your repo’s status via Settings > Manage Access > Who has access > Manage > Danger Zone > Archive this repository (settings#danger-zone). Contact open-source@llnl.gov if for some reason GitHub won’t let you complete this step.

The process to transfer organizational ownership is straightforward, but generally discouraged. This should really only be done for projects that are starting to build a “bigger than LLNL” community, and the decision should not be made lightly.

Migrating the repo outside of the LLNL organization requires an organization admin. Contact github-admin@llnl.gov to coordinate the move.

Once the repository has moved to the new organization:

1. Submit a pull request updating the input_lists.json file to add the new organization/repo’s name. This allows for the software catalog to continue including the project even after it moves.

2. Retain topic tags (e.g., math-physics) to connect it to this website’s browsable categories.

3. Update the org in the RADIUSS contributor-ci.yaml file, if applicable.

Refer to individual projects for their requirements on accepting contributions. (To contribute to this website, see our Contributing Guidelines.) In general, though, we follow the “fork and pull” Git workflow model:

1. Fork a repository.

2. Develop your changes in your fork.

3. Sync your fork to the upstream repository (git remote add upstream git@github.com:org/repo.git).

4. Create a pull request to the “upstream” repository.

5. If approved, changes will be merged in by a repository maintainer.