If you run the tests locally and get failures in tests/rendering/server.js around static assets, stylesheets, and/or the client-side JavaScript bundle, but the same tests pass in CI on a PR, you likely need to run npm run build. This is a one-time command that creates static assets locally.
See development.md for more info.
If a staging deployment is pending for more than 5-10min, try the following:
- Close the PR (don't delete the branch) and reopen it. This will trigger a new staging deployment. It won't break anything.
- If that doesn't work, trigger a new staging deployment by pushing an empty commit on the command line:
git commit --allow-empty -m 'empty commit to redeploy staging'
💛 If tests are stuck yellow for more than an hour, rerun CI by pushing an empty commit on the command line:
git commit --allow-empty -m 'empty commit to rerun CI'
If you are running npm start and get a Cannot find module error, try:
npm install
If that doesn't fix it, try:
rm -rf node_modules
npm install
Check out the branch and run the site locally:
npm start
Go to https://localhost:4000
You should see more information about the error in your browser or in your Terminal (or both).
If you see an error like this:
error parsing file: /Users/z/git/github/docs/content/dotcom/articles/troubleshooting-custom-domains-and-github-pages.md
(node:89324) UnhandledPromiseRejectionWarning: YAMLException: can not read a block mapping entry; a multiline key may not be an implicit key at line 4, column 14:
redirect_from:
^
make sure single quotes are properly escaped in the frontmatter. Also, check the formatting in redirect_from blocks.
Check out the branch and run the site locally:
npm start
Go to whatever page is 500ing on staging on your local server: https://localhost:4000/page-with-error
Again, you should see more information about the error either in your browser or in your Terminal (or both). Staging just shows Oops, but the local server should a stack trace for debugging.
The check internal links test reports any broken links on the site, including images. The test reports the URL of the broken link, not the file that includes that link, so you'll need to search the docs repository to find the file.
Broken images include assets/images/ in the URL and are often caused by images being versioned for previous versions of GHES but not uploaded to the appropriate folder in S3. Search the docs repository for the file name (e.g., assets/images/help/repository/security-tab.png), then make sure the image is versioned correctly in each result. If the image is in a reusable, you'll also need to search for each occurrence of that reusable. If the image is versioned correctly, upload the image to the appropriate folder(s) in S3.
For broken links to articles on our site, find the file that contains the link by searching the docs repository for the file name (e.g., incorporating-feedback-in-your-pull-request). Try the following fixes:
- Make sure the link is versioned correctly. For example, if the article only exists for 2.17+, make sure the link is versioned for 2.17+.
- If an article that is available for GHES links to a dotcom-only article, include the version in the path to prevent the URL from automatically converting to include a GHES version number:
[{{ site.data.variables.product.prodname_github_connect }} Addendum to the {{ site.data.variables.product.prodname_enterprise }} License Agreement](/free-pro-team@latest/articles/github-connect-addendum-to-the-github-enterprise-license-agreement/)"
For broken external links, investigate whether the site is permanently removed. If so, find an alternative site that provides equivalent context.
During development, you can visit any page on http://localhost:4000 and add ?json=page to the end of the path to show some underlying information that may be helpful for debugging. In addition to basic info like title and intro, these are a few fields that may be useful.
| Field | Description |
|---|---|
productVersions |
Shows what the site is parsing from the productVersions frontmatter. |
permalinks |
Shows all permalinks that the site is generating for the page. |
redirect_from |
Shows the hardcoded redirects in the redirect_from frontmatter. |
redirects |
Shows all redirects that the site is generating for the page. |
includesPlatformSpecificContent |
Shows whether the site detects any platform-specific content on the page. |
If your text or code example includes { or } that should render, you need to wrap it in {% raw %} {% endraw %} to disable Liquid processing for that section. For example:
-
Use:
GITHUB_TOKEN: {% raw %}${{ secrets.GITHUB_TOKEN }}{% endraw %} -
Avoid:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}