Set up your GitHub account
Next you will learn how to set up your own GitHub account, which you will use to submit contributions to Docs articles. The good news is, you'll only have to do most steps one time.
1. Create a GitHub account and set up your profile
To contribute to Docs technical content, you'll need to sign up for a GitHub account, if you don't already have one.
If you are a Microsoft employee, you must set up your GitHub account so that you're clearly identified as an employee. Set up your 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: list your location (optional)
Your profile should resemble the following when you're done :
To sign up for Livefyre feed notifications, please see Subscribe to SkyEye notifications.
2. Additional steps for Microsoft employees
2.a. Link your GitHub and Microsoft accounts (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, and so linking is not necessary.
However, we prefer that Microsoft employees contribute to private repositories when available. To do that, you must first link your Github account with your Microsoft account:
Visit https://opensource.microsoft.com/link to sign in and complete the steps to link your Github account with your Microsoft account. If your accounts are already linked, you should see a green "Link OK" graphic and need no further action.
From the https://repos.opensource.microsoft.com/ 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, for example:
https://github.com/<organization>/<repository>. Under the "Your Microsoft GitHub organizations" section, you will see the GitHub organizations you already belong to on the left, and additional available organizations on the right, which you can click to join.
After you've joined an organization, you will be added to the organization's "everyone" team, which many private repositories use as the read-permissions team. This may be the only step required, but if your team requires that you join a specific team/teams, click the "Team" link under the top GitHub/Teams menu, then click the "Available teams" button. Enter the team name given to you by your GitHub administrator in the search field, click Search, then click the team name in the results list and click "Join".
2.b. Enable two-factor authentication (2FA) and create an access token (Microsoft employees)
Microsoft employees must enable two factor authentication on their GitHub accounts in order to work in the private content repositories.
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 appropriate to your mobile device.
b. Be sure to download/save your two-factor authentication recovery codes if you didn't already.
c. Set a fallback SMS number for authentication, in the event 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, using the TOTP mobile app you configured above.
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 (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.
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 accessible when you need it.
2.c. Authorize the OPS build system to access your GitHub account (Microsoft Employees)
If you are 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 be submitting pull requests, during the build process:
- Navigate to the OPS portal.
- Authenticate with your GitHub credentials.
- Verify the organization name of your OPS repositories (for example, MicrosoftDocs) is listed under Organization access.
Click the Authorize openpublish button.
When authorized, you will be directed to the OPS portal home page, which you can close.
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. Please note that this feature is only available on English articles.
As an article author or contributor, you should also sign up for Livefyre so you can participate in the comment stream for the article.
Use a docs.microsoft.com page to create your Livefyre account. For example, you could pick this one: https://docs.microsoft.com/en-us/active-directory/active-directory-developers-guide.
At the bottom of the article, click the Sign in link at the top of the comments section.
At this point, you can either pick an identity provider for an existing account you would like to use for sign-in (left side), or click 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, enter your profile information as follows, then click Sign up.
- Username: your Microsoft email alias plus @MSFT, for instance: alias@MSFT
- Email: Your Microsoft.com email address
- Continue to the Tools setup page to install Git Bash, a Markdown editor, and more.