SSW.Rules Pipeline Troubleshooting Guide

Overview

SSW.Rules is a framework for managing content rules and guidelines aimed at enhancing workflow efficiency and ensuring consistent practices. This article outlines the common issues encountered with the SSW.Rules pipeline and provides a structured troubleshooting guide to identify and resolve these problems.

Important Links:

• Azure DevOps Rules Pipeline
• Rules Content Repo
• Rules Engine (Gatsby) Repo
• How to Test on Staging with a New Branch

Useful Tools:

• GitLens VSCode Extension

Video - Going through the below steps with Brook and Jack P

Common Issues with Rules:

Out of Memory Error

Figure: This issue typically occurs when there is a bad content change that has been merged.

GraphQL Error

Figure: This error generally arises from bad code changes or bad frontmatter in the content

Troubleshooting Steps

1. Identify Pipeline Failures:

   • Review the pipeline in DevOps to determine the exact time where the failure occurs. This helps narrow down the potential causes.
   • Record when the pipelines started to fail

2. Review Recent Commits:

   • Inspect commits to the Rules repository, particularly those involving significant changes or updates to dependencies or configurations.
     • Anything that might touch code that is to do with the Gatsby plugins, graphql queries or the page generation templates.
     • If a problematic commit is identified, consider reverting it to stabalize the pipeline.

3. Audit Content Repository:

   • Look at the content repository to see what was merged around the time problems began.
     • Create a branch and deploy it to a staging environment to test whether the changes are causing the issues. See: https://github.com/SSWConsulting/SSW.Rules/wiki/How-to-Test-on-Staging-with-a-New-Branch
     • TIP: Building a different branch locally can speed up the time. As the builds can be 50+ mins. Use yarn build locally to do this

4. Iterative Testing:

   • If a direct cause is not immediately evident, systematically revert or advance commits and test each state. (Do this on a branch)
     • Continue this process until you isolate the build that reintroduces the error or find a configuration that succeeds.

5. Check for Obvious Configuration Issues:

   • Frontmatter Validation:
     • Ensure all required fields are present, correctly formatted, and free of special characters.
       • No : in title
       • Spaces are correct. e.g. title:Hello is invalid. should be title: Hello
     • Required Rules frontmatter fields: type, title, uri, guid, created and author.
   • Rules Content Examination:
     • Verify that all necessary information is present and correctly formatted, particularly checking for the proper use of the ::: syntax.
   • Category Content Validation:
     • Confirm that YAML syntax is correct and only valid rule URIs are included in the index.
     • Ensure that all linked rules actually exist.

6. Repeat this process of branching, fixing, building and testing until the build successfully builds again.

7. Create a PR with the fix, merge into main and let the Product Owner know that the pipeline has been fixed. (Call them!)

Good Luck 🎉