DocumentationExperience League Authoring Guide

Migrating to GHEC

Last update: Thu Mar 19 2026 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 (autotagging) - see Autotagging content at the end of the article

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 have two 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 where we will use 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 the 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. The test migrations will be deleted prior to the final process. You’re welcome to test those repos. Let us know if you want to be more involved in testing.

Phase 0: Preliminary migration

The Eng team first runs a test migration on GHEC. The Eng team tests validation and rendering. If authors are interested in being involved during this phase, reach out to Bob.

Phase 1: Evaluation migration

The Eng team will work with the authoring team to determine a migration window. At the start of the designated week, Bob will migrate content to GHEC that outputs to stage only. The authoring team will evaluate the migration and rendering.

During this evaluation, authors can still edit in git.corp.

When the authoring team agrees to do a final migration, we’ll decide on a final migration date and time. This sets up a lock-out window in which no edits are allowed.

Phase 2: Final migration

Authors should check in their local edits to the server before the designated migration window. Bob will run final migration and notify the Loc team.

During this quiet window, DO NOT EDIT THE REPO.

When the migration is complete for all languages, authors can begin working in GHEC:

  • Authors should delete the git.corp clone.
  • Authors should create a new clone. See Configuring GitHub Desktop later in this article.

Feel free to reach out to Bob if you want more details or a demo.

Pay attention to the sccm-assistance Slack channel, email, and the GHEC migration plan wiki page for when your repos are scheduled to migrate.

Incomplete or missing pipeline features

Note the following migration issues:

  • Review environment using the review branch is not yet fully hooked up (in-progress).
  • GitHub public mirror is not yet in sync with GHEC. The mirror content will be stale after the repo is migrated. In-progress.
  • Known issues will bulk publish jobs for larger repos.
  • Last update date is not reliably being updated.
  • Generate exl-ids for new GHEC articles is not yet available in GHEC.
  • Migrated repos are no longer tracked in Jenkins reports such as Page counts. Reports will not be updated until migration is complete.
  • Next Page and Previous Page buttons are not yet implemented. TBD.
  • Ongoing UI rendering fixes (mostly edge cases).
  • In some cases, authors can merge PRs even if validation fails. The content is rendered as well as possible. Updating the branch rule to add the validation job will prevent a failed PR from merging.

JIRA list of open tickets

GHEC Gotchas

  • The VSC Adobe Authoring plugin has not yet been updated with the new validation rules. Take those suggestions with a grain of salt, especially around spacing in tables.
  • When you first create a Pull Request in GHEC, it takes a few seconds for validation to start. Wait for validation to finish before you merge the PR.
  • In some cases, the jobs that run validation and publishing will sometimes time out, especially with larger jobs. We’re still working on improving reliability of bulk publishing.

New syntax

  • Preview before publish - Use metadata to preview before publish is nearly complete. Add hold: true to the article metadata to publish to preview, not production. Remove the hold: true tag when you want to publish to production. The Slack notification provides URLs for both production and preview updates.
  • New {hide-from-toc} syntax - Instead of adding hidefromtoc: true metadata to the article you want to hide from the left nav, a {hide-from-toc} parameter needs to be added to the article or section in the TOC. (Example: + {hide-from-toc} [Beta features](beta-features.md).) During migration to GHEC, we will convert all hidden metadata to use the new format. Once your repo is migrated to GHEC, you will need to tag the TOC with metadata instead of the article.

See Metadata for details.

Tighter syntax rules

Quick summary

  • HTML syntax - Some HTML syntax   especially complex or erroneous comment syntax   causes content to disappear in V2. To prevent these errors from occurring, we have created a new validation rule.
  • Deprecated roles - In V1, we allowed deprecated roles (Data Engineer, Data Architect, and Architect) to be used even though these values were mapped to Developer. In V2, we no longer support these deprecated values. (It’s likely we’ll expand role values later with the new metadata taxonomy.)
  • Table, note, and code block syntax - See below for details.

Here are examples of new or updated syntax errors in v2 that are different from v1. Please let us know if you want to add, remove, or edit validation rules.

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 the 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 the lists. This rule also applies to lists in notes.

  • MD037 - Spaces at the start or end of emphasis syntax are 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 are 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 don’t indent 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 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])

  • AM015 - Comment syntax (in-progress)

    Flags commenting problems such as unmatched open/close syntax, nested syntax, and multiple comments in the same paragraph. In-progress.

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

  • AM054 - Commenting requirements.

    There are now tighter rules for comment syntax:

    • To comment out a section with multiple lines, the open (<!--) and close (-->) comment tags must be on their own lines.
    • You must use the same comment syntax type for the syntax, such as <!--/--> and not <!---/-->.
    • You cannot use multiple inline comments in the same paragraph.

Pre-migration cleanup

FYI, here are some searches I run to clean up repos prior to v2 migration.

Removing deprecated role values

Architect, Engineer, and Data Engineer are currently allowed in v1 but mapped to Developer. In v2 validation, those deprecated values are no longer allowed. Here are expression searches that 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 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 \| $ (turn on search expressions)

Replace with |

Some tables 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.

Multi-line comments

recommendation-more-help
92f1a422-8a81-400b-85d3-388f0c36dfda