Resolve Validation Errors

Whenever you submit a pull request or commit to main, two validation checks occur:

  • (Git/Kodiak) Check for conflicts between the main branch and your content
  • (Jenkins) Check to make sure your content is well-formed

Whenever a pull request to main is created, GitHub checks for merge conflicts as part of its built-in functionality. In addition, we have extended GitHub to run a series of tests on the code using the Jenkins platform to see if content can be published without problems.

When you submit a pull request, you can see the status of these checks on the pull request page:

validation success image

In this case, both validation passes were successful. When that happens, you can merge your pull request. If one or both of these validation passes fail, this article explains how to fix the errors.

Validation summaries

Validation summaries appear in your pull request and in Slack.

Slack notifications

By default, when you commit to the main branch, you’ll receive a Slack notification for the EXL job. If it fails, it looks something like this:


The errors (and only the errors) are listed as part of the Slack message.

If the job succeeds, it looks something like this:


You’ll get a different publish button (Publish or Publish Now) depending on whether your repo is set to auto-activate. If your content is valid but preview fails, you get a Publish Anyway button.



If you don’t get a Slack summary when you commit to main, it’s likely that your Git email isn’t specified. In GitHub Desktop, go into Preferences (Mac OS) or Options (Windows), choose Git, and make sure your full email address including is specified.

Pull request summaries

When you submit a pull request, you do not get a Slack notification. However, the validation summary (including errors) appears in the GitHub page.

PR validation

Configure auto-activate and Slack settings

  1. Use your LDAP account to sign in to Jenkins.

    If you’re a contractor, you might need to get access rights. Contact IT to request to add to the list of approved servers for the “Vendor_Basic” VPN.

  2. To change auto-activate or Slack notifications, open your repo in the appropriate tab (EXL, PRs, or Review), and click Configure.


  3. Do any of the following:

    • Turn on or off AUTOACTIVATE (applies only to EXL jobs, not PRs or Review).
    • Turn on or off Slack notifications (SLACKNOTIFY).
    • If Slack is on, get a Slack notification for anyone’s commit to main branch, not just yours (SLACKUSERS) by adding your Slack name (e.g., @bbringhu) to the Default Value field. Or, if you want to see Slack summaries only for failed validations in that repo, add your Slack name to SLACKERRORSONLY.

Resolve Jenkins validation errors

The Jenkins validation check makes sure that your content is properly formatted before it goes through the pipeline and into preview.

Jenkins and validation details

Jenkins is a popular open-source automation server. It is responsible for testing and deploying all changes that are made to our markdown on GitHub.

Pipelines - Jenkins is made up of pipelines. In Jenkins, a pipeline can be any kind of workflow. For our documentation, a pipeline represents the workflow of taking changes created in a pull request, building them, testing them, and uploading them.

Jobs - Each pipeline has jobs associated with it. A job is an execution of the pipeline. Each job is recorded so that there is a detailed log of all jobs processed.

There are three types of jobs:

  • _exl job - When you commit to main branch, a <repo>_exl job kicks off. If validation checks pass, the content is uploaded for preview:
  • _pr-exl job - When you submit a pull request, a <repo>_pr-exl job kicks off.
  • _review job - When you commit to review branch, a <repo>_review-exl job kicks off. If validation checks pass, the content is staged for review:

Understanding Validation Errors

Validation checks to make sure that you don’t have any broken links and that you’re using valid Markdown syntax. Errors are listed in the validation summary that appears in Slack or your pull request page.

Markdown syntax

Most of the errors you see in this section are self-explanatory. You get the Markdown filename, a description of the error, and the line number where the error occurs. See the Syntax Style Guide.

To fix a syntax error, open the file containing the error. Make sure that you open the file in your branch if you submitted a pull request, not in main. Then edit the file and commit the changes to your branch. Committing the change to your branch automatically triggers a new validation job.

Illegal Characters

Certain characters like bite order marks would cause rendering problems if allowed. Many of these characters are added accidentally by copying and pasting content from other applications. Illegal characters such as hard tabs and vertical spaces can also show up as errors under Markdown Syntax.

Redirects Processing

Validation checks the redirects.csv file to make sure there are no duplicate source URLs, redirect chains (A > B, B > C, etc.), or other redirect errors, including invalid destination URLs.

Package and Structure (TOC)

Validation checks the TOC file and article metadata.

  • In the file, the relative links to articles must be valid. See Working with TOC files
  • Only one relative links to an .md file is allowed in a TOC.
  • Metadata in the TOC or article must be valid. For example, if the specified feature value doesn’t match up with the approved list of values, it’s flagged as an error. See Metadata.
  • Links to archived doc sets and non-production links are flagged as errors.

Relative links to images or markdown files are flagged as errors that stop validation.

See also Checking for broken absolute links and Linking tips.

HTML Generation Preflight

In some cases, content passes validation but doesn’t render properly. To try to close the gap between content validation and the rendering engine, we run the content through the rendering engine to try to catch any of these unidentified errors. Contact sccm-assistance if you see this error so that we can update the validation rules, if applicable.

Landing Page Check (Optional)

If your content is linked to from landing pages and you make a change that would update the URL, this change is flagged as a warning.

Redirects Check (Optional)

You get a warning if have links to other repos that no longer exist or that are being redirected (we can’t always tell). You should check those links to make sure that they don’t result in a 404.

Similarly, if writers are linking to your content from other repos, and those links don’t exist, you get a warning. In some cases, you should add a redirect for a file that’s been moved or deleted.

See Redirects.


Validation checks to make sure the processed files are uploaded successfully to the server where it’s rendered for publishing. The upload could fail due to a system outage or network issue.

If Upload is successful, changes will go live within a two-hour window even if preview fails.


In some instances, your job shows up as red even though there are no content errors. These ‘false failures’ are caused when the job times out due to a pipeline issue. If you see that everything passes except for preview, it’s usually the result of a timeout failure. Preview failure are usually intermittent. If your repo fails to preview persistently, please notify sccm-assistance.


If auto-activation is enabled, your changes will go live within 2 hours, even if preview fails.

Absolute links to URLs are checked once a day (1:00 AM PT) in all EXL repos; results are displayed here. Broken absolute links do not cause validation to fail; however, you should fix broken or problematic absolute links.

The daily-generated list of broken links appears here:

link check


While the list of broken absolute links is generated once a day, you can run the job at any time to see updated numbers. Go to LinkCheckExl, click Build with Parameters and click Build. The job takes about 10 minutes to run.

To check repo for broken absolute links:

  1. Open your repo in Jenkins.

  2. Choose Build with Parameters.

  3. Select the FULLLINKCHECK check box (and REPORTONLY to generate only the log file without deployment).

    full link check

  4. Click Build.

    • Any missing or forbidden external link will generate an error if the link is broken or a warning if the link timed out or is not secure (http instead of https). However, broken external links will not cause validation to fail.
    • Any missing internal link will still be a validation error.
  5. When the job finishes, click External Link Check in the Slack summary or navigate to the external-link-check.log file in your Jenkins job.

  6. Fix your broken links by doing any of the following:

    • Edit links that are flagged as errors.
    • Put sample website links (such as in code blocks so they aren’t rendered as links.
    • For valid websites that are being flagged for some reason, add them to the exclusion list file (linkcheckexclude.json) in your repo. See the next section for details.

These settings are not sticky; the next time you run a job, any check box you selected will be turned off. (Use Config to change settings going forward.)

For dummy URLs such as, the preferred method for preventing a URL from being checked is to wrap it in a code block. However, in some cases, such as when you specify URLs that are available only after a sign-in, the URLs will be flagged as warnings. If you don’t want certain URLs to be flagged during validation, you can add URLs patterns to the linkcheckexclude.json file in your repo.

  1. Open the linkcheckexclude.json in VSC or another editor.
  2. Copy the first pattern section (including the comma) and paste it before the last section.
  3. Edit the copied section to include the pattern you want to exclude.

exclude url

In this example, LinkedIn URLs were being flagged as warnings, so the writer added the "^.*" pattern to make these warnings go away.

Markdown validation technical details

We use markdownlint as the basis for validating Markdown syntax. The markdownlint Visual Studio Code extension includes a library of rules to encourage standards and consistency for Markdown files. See this markdownlist readme file for a description of the rules we start with.

The pipeline includes a markdownlint.json file that includes custom rules and turns off rules we don’t want to use. (We turn off MD009, MD012, MD014, MD026, MD028, MD030, MD039, MD027, MD038, MD026, MD024, MD036, MD040, and MD045.) Each repo includes a markdownlint_custom.json file for turning off rules within that repo.


For editing in Visual Studio Code, an Adobe Markdown extension pack is in its final stages. For now, we recommend that you use the markdownlint extension.

This extension does not include our current set of rules, but it’s still helpful. We’re working on an Extensions Pack for Adobe that will include these rules.

Matt’s wiki

Matt’s Jenkins documentation

Resolve Git conflicts

A Git conflict occurs when an edit in your branch is in conflict with an edit in the main branch that occurred since you created your branch.

The most common Git conflict occurs when two people try to make changes to the same section of content within an article.

  1. When you submit a pull request, check to see if there’s a conflict between your branch and the main.

    Git conflict image

  2. Click Resolve Conflicts.

    Git conflict editing image

    In this example, one person changed “AEM rendered” to “staged” and another person added links in the same line. Git doesn’t know which change to pick, so it flags the conflict and makes you decide.

  3. Edit the section or sections with conflicts. Remember to remove the extra lines that are added.

  4. Click Mark as resolved.

    Git conflict editing image

  5. Click Commit merged.

Clicking the “Commit merged” option commits the changes you made to your pull request. You can then go on to merge the pull request, assuming of course that the Jenkins validation check passes. If not, well, keep reading.


What if “Resolve Conflicts” is dimmed?

If “Resolve Conflicts” is dimmed, it means there is a Git conflict that cannot be resolved in the editing view. For example, if one person deletes, moves, or renames files that another person edits, that’s a more gnarly problem. You usually need to make the same file changes in the branch and then commit the changes to that branch. Or, contact a member of the SSE team or your local Git expert to help you resolve it.

If you’re willing to blow away the changes to resolve this conflict, select the branch in GitHub Desktop, choose Repository > Open in Terminal and enter git reset -hard main and then git push --force (it’s the equivalent of deleting/re-creating the branch).

On this page