Documentation Experience League Authoring Guide

Migrating to GHEC

Last update: Thu Dec 18 2025 00:00:00 GMT+0000 (Coordinated Universal Time)

The migration consists of three major changes

Migration from Git Corp to GitHub Enterprise Cloud (GHEC)
Replacing current v1 pipeline architecture with v2 architecture
Replacing metadata taxonomy

GHEC migration

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 be a transition period in which we’ll be using both git.corp.adobe.com/Adobe-Enterprise-Docs and Enterprise github.com/AdobeDocs for authoring.

Public github accounts show up as <name>, and Enterprise github accounts show up as <name>_adobe.

github names

Overview of migration process

Migration occurs in two stages: a test phase and a final migration.

Note that the Eng team is also migrating multiple repos for testing purposes. We will delete these test migrations prior to the final process. You’re welcome to test those repos. Let us know if you want to be more involved in testing.

Test migration

The Eng team first runs a test migration on GHEC and notifies authors. Authors can edit this test repo in GHEC, but all changes will be blown away when testing is complete. Authors can keep editing in git.corp during this test period.

Final migration

The Eng team will then notify the authors when they are ready to do the final migration. At that point, authors will check in their edits and wait for the final migration to be completed. During this quiet window, DO NOT EDIT THE REPO. Once the migration is finished for all languages, authors can begin working in GHEC. Here is this process broken down into stages:

[] Eng team notifies writers of repo migration.
[] Eng team migrates repo to GHEC for testing. Authors can keep editing in git.corp.
[] Testing on stage for rendering validation.
[] Eng team notifies writers of date for git.corp check-in and start of quiet period.
[] Eng team renames test GHEC repo (such as OLD_<repo>.en).
[] Quiet period for <repo>.en on git.corp (2 hours to a day).
[] Final migration from git.corp to GHEC.
[] Loc team implements and tests.
[] Authors to remove old git.corp clone and create new GHEC clone.

Pay attention to the sccm-assistance slack channel, email, and the GHEC migration plan wiki page for when your repo(s) will be migrated.

Incomplete or missing pipeline features

The following features are not yet ready but required for MVP.

Stage for author review (currently stage and production go live right away on commit to main)
Prevent pages from updating if validation fails (all edited pages are rendered on commit to main)
UI rendering bugs such as broken relative links and incorrectly rendered components
GitHub public mirror sync with GHEC (mirror content will be stale for now)
Generate exl-ids for new GHEC articles (not yet available in GHEC)
Review environment not available
Next Page and Previous Page buttons not yet implemented
Authentication for admin API

JIRA list of open tickets

Tighter syntax rules

Here are examples of new or updated syntax errors in v2 that are different from v1.

Common markdown linter rules

MD005 - Inconsistent indentation for list items at the same level

Items in bullet and numbered list need to have the same number of indent spaces.
MD010 - No hard tabs

Hard tab characters need to be spaces.
MD031 - Code blocks should be surround by blank lines

You need blank lines above and below code blocks. This rule also applies to code blocks in notes.
MD032 - Lists should be surrounded by blank lines

You need blank lines above and below lists. This rule also applies to lists in notes.
MD037 - Spaces at the start or end of emphasis syntax no longer allowed.

Syntax such as **This is bold** won’t pass if there is a space after the start syntax or before the end syntax.
MD038 - Spaces at the start or end of code blocks no longer allowed.

` VisitorAPI.js` will be flagged.
MD046 - Code block style inconsistency

This rule is tricky to troubleshoot. There are basically two ways to create code blocks: with triple backticks (fenced) or by indenting. The MD046 error mentions that a code block is fenced when it should be indented. What makes it tricky is that the error usually happens much earlier in the file with an improper indent in a list. Look before the line number to make sure that nested items between lists are indented properly and that you haven’t indented a line unless it’s in a step. Or ping Bob.

MD055/MD056 - tables

For example, pipe characters in tables need to be preceded by a backslash in order to display. Tables must have the same number of pipe characters.

note note
NOTE
During testing, check your HTML tables to make sure they render properly. We haven’t been able to validate every syntax issue that can cause a problem. Let us know if you find a table that doesn’t render properly.

Custom Adobe linter rules

AM004 - Malformed table

Spaces are not allowed after the closing pipe character in a table row.
AM009 - Malformed note

Catches issues like >![NOTE] (should be >[!NOTE])
AM016 mismatched symbols not escaped.

Syntax such as '{' will be flagged unless you escape the characters.
AM020 - frontmatter-validation, especially deprecated role values

Old deprecated role values no longer allowed: Architect, Engineer, Data Engineer
AM030/AM031 - Anchors cannot be one of the reserved anchor ids

For example, a {#search} anchor can cause problems for some rendering engines.
AM046 - Missing links not found.

Broken links in unused .md files (files not in TOC) are now flagged as errors. To remove these errors, either rename the file suffix (such as overview.draft or readme.txt) or fix/comment out the links.

This rule also flags bad links such as this (note the redundant brackets):

[requisition lists](<https://experienceleague.adobe.com/docs/commerce-admin/b2b/requisition-lists/requisition-lists.html>)

and this: [link text](file.md/#deep-link) (need to remove slash for link to work)
AM047 - Invalid filenames

In v1, we intercepted and changed filenames that include underscores and uppercase letters. In v2, we flag invalid filenames such as sendPushSubscription.md or send_push.md as errors.
AM049 - TOC validation

There are tighter rules for TOC.md files. For example, adding inline comments to TOC entries is now flagged to avoid rendering problems.

Pre-migration cleanup

Here are some searches you can run to help clean up.

Removing deprecated role values

Architect, Engineer, and Data Engineer are currently allowed in v1 but mapped to Developer. In v2 validation, these deprecated values are no longer allowed. Here are expression searches you can run in VSC to find these:

Find: role: Architect (then Engineer and Data Engineer)

Find: role: (.+?), Architect (then Engineer and Data Engineer)
Replace role: $1, Developer (check to make sure you don’t add multiple Developer tags)

Spaces in link text

A link such as See [ Widgets](widgets.md) will now be flagged.

Find: [ followed by a space, and then a space followed by ].

Unescaped snippet text

Search for {{ and }}. If it’s not a legit snippet, surround it with back ticks to escape it.

Trailing spaces in tables

Search for \| $

Replace with |

Some table have multiple trailing spaces after the pipe character. Add more spaces between the | and $ characters in the “Search for” field until you don’t get any results.

Signing in to GitHub Enterprise Cloud

Make sure that you are signed in to VPN (GlobalProtect) or are using AdobeCorp in the office.

Unlike git.corp, GHEC requires VPN or AdobeCorp.

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.

note tip
TIP
To be able to switch easily between your github.com enterprise account and github.com public account without having to sign in again, see Switching between accounts.
Another option is to use one browser for GitHub Enterprise and a different browser for public GitHub. That way, you don’t have to sign in and out all the time.

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.

NOTE

If you get a "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:

GHEC Access User Account wiki - troubleshooting

Configuring GitHub Desktop

While repos are being migrated, you’ll likely need to edit some repos in git.corp.adobe.com and other repos in GitHub Enterprise. During this interim period, you should add both Enterprise accounts to GitHub Desktop.

Make sure that you can sign in to the new org on GHEC (see the previous section).
If you use GitHub Desktop, open Settings (Mac OS) or Properties (Windows), and then click Accounts.
Click Add GitHub Enterprise account (you might need to delete your public github.com account), and then specify https://github.com/Adobe-Enterprise-Docs/ as the URL. Sign in using your LDAP.

Setting up the new repo in GHEC

When you get the notification that your repo has been migrated, 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.
Create a clone of the new GHEC repo using the same process in GHEC as it was in git.corp.

Make sure that you’ve added your GitHub Enterprise account to GitHub Desktop settings as described earlier in this article. If you try to clone the repo in GHEC and get a prompt to install GitHub Desktop even if it’s already installed, it means your GitHub Desktop account isn’t signed in properly to GitHub Enterprise.
Test the new repo to make sure everything is set up properly. Let us know if you have any issues.

GitHub Enterprise Migration notes

All history, branches, and branch-based pull requests are preserved in the migration. Fork PRs will not migrate with the repository.
Settings such as branch protection, team/user access, webhooks, and custom items such as wiki workflows need to be re-created.
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.

recommendation-more-help

92f1a422-8a81-400b-85d3-388f0c36dfda