Git/Visual Studio Code setup
Welcome, Adobe writers. If you’re new to the GitHub workflow, see these articles:
Switching to Github Enterprise Cloud (new) sign-in-to-github-enterprise-cloud
Adobe is moving from the old Enterprise account at git.corp.adobe.com to the new GitHub Enterprise Cloud (GHEC) across the board. While switching to GitHub Enterprise is going to offer several feature and security advantages, it might be difficult and confusing for some of us to make the transition. For example, we will now have two different github.com accounts: Public and Enterprise. We’ll need to use a Public github.com account for the public mirrors and our Enterprise github.com account for authoring content. There will also be a transition period in which we’ll be using both git.corp.adobe.com and Enterprise github.com.
Public github accounts show up as <name>, and Enterprise github accounts show up as <name>_adobe.
Preparing for the GHEC migration
Migration of repos to GHEC will go in batches. We’ve migrated a few internal repos successfully. Migration of customer-facing repos will start in mid-August.
- Make sure that you can sign in to the new org on GHEC (see the next section).
- Pay attention to the slack channel and to the GHEC migration plan wiki page for when your repo(s) will be migrated.
- When your repo is migrated, delete the git.corp clone of the old repo (including files) and add the new GHEC clone.
- Test the new repo to make sure everything is set up properly. Let us know if you have any issues.
Signing in to GitHub Enterprise Cloud
-
Make sure that you are signed in to VPN (GlobalProtect) or using AdobeCorp in the office.
-
Sign in to GitHub - Adobe Enterprise Docs using your LDAP.
If this is the first time you have signed in to Enterprise
github.com, an Enterprise GitHub account is created for you.Note that this Adobe Enterprise account is different from a personal GitHub.com account you may have created. You can sign in to only one account at a time in a browser, unless you use Incognito or Private tabs.
-
If you don’t have access to a repo, ask Bob (bbringhu) or another Org Owner to give you Write or Admin access to any repo you’ll be working on.
By default, new members have Read access. You’ll want Write or Admin access for any repo in which you’ll need to publish content.
"User is not assigned to this application" error message when you try to sign in, you might have run into a bug that causes some migrated accounts to be suspended. This bug causes some account names such as johndoe_adobe to be mistakenly changed to something like behseflsi13sfeds_adobe, and the account no longer works. Follow these steps to ask Adobe IT to resolve the issue:Using GitHub Desktop and cloning migrated repos
While repos are being migrated, you might need to edit content in both git.corp.adobe.com and GitHub Enterprise. During this interim period, we recommend that you add both Enterprise accounts to GitHub Desktop.
When your repo is fully migrated to GitHub Enterprise, we recommend that you remove the git.corp.adobe.com clone and add the new GitHub Enterprise clone.
To remove the git.corp.adobe.com, select the repo in GitHub Desktop, and then choose Repository > Remove.
Creating a clone is the same process (described below).
GitHub Enterprise Migration notes
- All history, branches, and pull requests are preserved in the migration.
- Settings such as branch protection, team/user access, and webhooks need to be re-created.
- Currently, migration works only for English repos. The Loc team is working on updating their configurations.
- GHEC repos will require tighter branch protection rules, including mandatory pull requests: GHEC Branch Protection Rules wiki.
- Repos will be migrated in batches. See ExL content repo migration plan wiki.
Sign in to Enterprise git.corp.adobe.com (legacy)
Here are instructions for git.corp.adobe.com, which will go away soon.
If you haven’t already set up your tools:
-
Sign in to VPN (GlobalProtect).
-
Sign in to Git AdobeDocs.
Use your LDAP account to sign in. If this is the first time you have signed in to
git.corp.adobe.com, an Enterprise GitHub account is created for you.Note that this Adobe Enterprise account is different from a personal GitHub.com account you may have created, even if you used your Adobe email address to sign up for GitHub.com. Git Corp and Github.com are two separate systems.
-
Ask Bob (bbringhu) or another Org Owner to (a) add you as a member of AdobeDocs, which gives you Read access to all repos, and (b) give you Write or Admin access to any repo you’ll be working on.
By default, new members have Read access. You’ll want Write or Admin access for any repo in which you’ll need to publish content.
Contractor or vendor access
In order to get full access to Jenkins and EXL stage, contractors should do the following:
-
Log a ticket with IT. Ask them to update your VPN Group to allow access to the following:
docs.ci.corp.adobe.com(Jenkins validation)experienceleague.corp.adobe.com(EXL stage)
Paul Gilliham is the group owner who should approve the request.
Install tools install-tools
-
Decide which Git client and Markdown editor you want to use.
Most of us use GitHub Desktop for the client and Visual Studio Code for the editor.
Both are free. Some people prefer using SourceTree or command line tools for the client. That’s fine.
-
Sign in to GitHub Desktop (if you’re using it as a client).
Make sure you’re signed in to VPN or AdobeCorp. In GitHub Desktop, go into Preferences > Accounts and specify your GitHub Enterprise Server user name and password. Use your Adobe LDAP info.
You must be signed in to Adobe Corp or VPN to use the GitHub Enterprise Server.
-
(Recommended) Install Git on your computer.
Installing Git improves the communication between Visual Studio Code and Git/GitHub Desktop.
On a Mac, the Homebrew option works well. Contact Bob if you need help installing.
-
Customize Visual Studio Code (if you’re using it as an editor).
- Install the Adobe Markdown Authoring plugin.
- See VSC add-ons for a list of other extensions we find helpful.
-
Consider installing the AdobeDocs Chrome Extension.
-
Become familiar with Adobe Markdown syntax.
-
Continue to learn Git.
-
If you want a demo or if you have questions, feel free to reach out to Bob. If you have questions about editorial issues or guidelines, contact Blake or Alva. We’re available through Slack and email.
Clone a repo clone-repo
Cloning a repository lets you work on files locally. These steps assume you are using GitHub Desktop as a client. If you’re using a different GitHub client, adjust the steps accordingly.
You only need to clone a repo once. Before you edit the cloned files, make sure your local clone is in sync with the server.
-
Go to the repository’s git Enterpriese page in your browser and click the Clone or download button on the right side, and then click Open in Desktop.
You can also clone directly from within GitHub Desktop via File > Clone Repository. If you use this method, make sure that you clone the Enterprise version, not the public mirror.
-
Click Allow to open GitHub Desktop.
-
Specify the location of the cloned files (the default is a “GitHub” folder in your Documents folder).
-
Click Clone.
-
In GitHub Desktop, click Fetch Origin to pull the files down from the server to your hard drive.
-
Open the Markdown files in your editor of choice, and save the Markdown files. Any changes you make to the cloned files are listed in GitHub Desktop.
Obtain access rights
If you need rights to merge pull requests or perform related tasks in your repo, contact the lead writer or Bob.
Turn on Git notifications
Each repo on AdobeDocs should have both an Enterprise version available only to Adobe users and a public mirror for anyone outside the company. Keep in mind that notification settings for these two Git areas (git.corp.adobe.com/adobedocs and github.com/adobedocs) are different and require different log-in accounts and separate configurations.
You can enable notifications so that you get an email message whenever anyone logs an issue or submits a pull request for the public docs on github.com.
Change Git settings for repo (lead writer/admin)
By default, when you create an AdobeDocs repo in Git Corp, anyone who has access to the repo can commit changes directly to the main branch without waiting for validation or review. You might want to change these settings to require validation to pass.
-
Make sure that you have admin rights to your repo. Contact the SSE team if necessary.
-
Open your repo on
git.corp.adobe.comand click the Settings tab. -
Click Branches in the left rail.
-
Click Add Rule if there is not an existing rule for the
mainbranch. (Click Edit if there’s already a rule formain.)If you’re creating a rule, specify the branch name such as master or staging in the Branch name pattern field.
-
Specify the branch protection rules.
-
(Optional) Select Require pull request reviews before merging if you want someone to acknowledge approval before a PR is merged. (Writers usually choose not to select this option.)
-
(Recommended) Select Require status checks to pass before merging and specify Validation. This requires the pull request to pass Jenkins validation before it can be merged to master.
-
(Optional) Select Require branches to be up to date before merging if you want to make sure that the main branch is up to date. Selecting this option can help reduce Git conflicts, but updating the main branch re-triggers validation. With larger repos, re-running validation can be time-consuming, especially during a release cycle when multiple writers are updating the main.
-
(Optional) Select Include Administrators if you want everyone, including admins, to wait for validation to succeed. (Writers usually choose not to select this option.)
-
(Optional) Select Restrict who can push to matching branches (recommended) and specify the members of your team, if anyone, who can push directory to master. When this option is selected, only the specified team members can commit directly to master. Everyone else needs to submit a pull request from a branch.
note note NOTE When you restrict who can push directly to master, writers can get stuck in GitHub Desktop when they accidently attempt to commit the changes to the main branch instead of a different branch. When this happens, have an admin go change settings to allow the changes to go through, and then change the settings back. (There’s probably a better way to handle this in GitHub Desktop, but I haven’t figured it out…)
-