GitHub and Livefyre account setup

Set up your GitHub account

To contribute to Docs technical content, you need to set up your own GitHub account. The good news is, you have to do most steps only one time.

1. Create a GitHub account and set up your profile

If you don't already have a GitHub account, create one.

Note

If you're a Microsoft employee, you must clearly identify yourself as one. Set up your GitHub profile as follows:

  • Profile picture: A picture of you (required).
  • Name: Your first and last name (required).
  • Email: Your Microsoft email address (optional).
  • Company: "Microsoft Corporation" (required).
  • Location: Your location (optional).

Your profile should resemble the following when you're done:

GitHub profile example

To sign up for Livefyre feed notifications, see Subscribe to SkyEye notifications.

2. Additional steps for Microsoft employees

Anyone with a GitHub account can contribute to Docs content by using one of our public repositories. No additional permissions are required for public content repositories, so linking is not necessary.

However, we prefer that Microsoft employees contribute to private repositories when they're available. To do that:

  1. Go to the Microsoft Open Source linking page to sign in and complete the steps to link your GitHub account with your Microsoft account. If your accounts are already linked, you see a green Link OK graphic and you can skip to the section about enabling two-factor authentication.

  2. From the Microsoft Open Source organizations page, join the appropriate GitHub organization where you will be collaborating with others on repositories, such as the "Microsoft" and "MicrosoftDocs" organizations. This is determined based on the organization where the repository resides: https://github.com/<organization>/<repo>. In the Your Microsoft GitHub organizations section, you can see the GitHub organizations that you already belong to on the left, and additional available organizations on the right. Select an available organization to join it.

  3. After you've joined an organization, you are added to the organization's "everyone" team, which many private repositories use as the read-permissions team. This might be the only step that's required. But if your team requires that you join a specific team:

    a. Select the Team link under the top menu, and then select the Available teams button.

    b. Enter the team name given to you by your GitHub administrator in the search field, and then select Search.

    c. Select the team name in the results list, and then select Join.

2.b. Enable two-factor authentication and create an access token (Microsoft employees)

To work in the private content repositories, Microsoft employees must enable two-factor authentication (2FA) on their GitHub accounts.

  1. To enable 2FA, please see the instructions in the Securing your account with two-factor authentication (2FA) GitHub article. We recommend the following steps, as covered in the article:

    a. Read Configuring two-factor authentication via a TOTP mobile app, which walks you through downloading the TOTP mobile app that's appropriate to your mobile device.

    b. Download and save your two-factor authentication recovery codes if you didn't already.

    c. Set a fallback SMS number for authentication, in case you lose access to your primary device and recovery codes.

    The first time you authenticate to GitHub from Git, you'll be asked to provide your 2FA authentication code by using the TOTP mobile app that you configured in this procedure.

  2. After you enable 2FA, see Creating an access token for command-line use to create a security token that will be used for authentication when you access GitHub by using command-line functions. When you create the token, select all the scopes available in the token-creation UI. (You can get details on each scope.)

    Your access token will be used instead of your GitHub password whenever you access a GitHub repository from the command line.

    Important

    The access token is not the authentication code that you get in a text message when you set up 2FA. It's a long string that looks similar to this: fdd3b7d3d4f0d2bb2cd3d58dba54bd6bafcd8dee.

After you create your access token, save it in a safe location to make it readily available when you need it.

2.c. Authorize the OPS build system to access your GitHub account (Microsoft employees)

If you're a Microsoft employee, you must also give the OPS build system authorization (also known as "consent") to access information contained in your GitHub account profile. This is required so the build system can access profile information such as your Microsoft email address, as well as the repositories where you will submit pull requests, during the build process.

  1. Go to the OPS portal.
  2. Authenticate with your GitHub credentials.
  3. Verify that the organization name of your OPS repositories (for example, MicrosoftDocs) is listed under Organization access.
  4. Select the Authorize openpublish button.

    OPS authorize application

When you're authorized, you will be directed to the OPS portal home page. You can close it.

Set up your Livefyre account

Every published Docs article supports a comment stream provided by the Livefyre service. Livefyre allows readers to comment not only at the bottom of a page, but also on any part of a page, at the sentence or paragraph level. Note that this feature is available only on English articles.

As an article author or contributor, you should sign up for Livefyre so you can participate in the comment stream for the article.

  1. Use a docs.microsoft.com page to create your Livefyre account. For example, you can pick this one: https://docs.microsoft.com/en-us/active-directory/active-directory-developers-guide.

  2. At the bottom of the article, select the Sign in link at the top of the comments section.

  3. Pick an identity provider for an existing account that you want to use for sign-in (left side). Or select Create New Account to create a new account based on an email address (right side).

    If you are a Microsoft employee, you must use the latter. In the authentication dialog box, enter your profile information as follows, and then select Sign up:

    • Username: Your Microsoft email alias plus @MSFT, like this: alias@MSFT
    • Email: Your microsoft.com email address.

Next steps

  • Continue to the Tool installations article to install Git Bash, a Markdown editor, and more.