-
Notifications
You must be signed in to change notification settings - Fork 18
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
EXM-50717 Blog post about using GitHub actions.
- Loading branch information
1 parent
233b411
commit d91fd4b
Showing
5 changed files
with
98 additions
and
1 deletion.
There are no files selected for viewing
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
96 changes: 96 additions & 0 deletions
96
topics/building_validating_and_publishing_using_github_actions.dita
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,96 @@ | ||
| <?xml version="1.0" encoding="UTF-8"?> | ||
| <!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd"> | ||
| <concept id="building_and_publishing_using_github_actions"> | ||
| <title>Building Validating And Publishing Using GitHub Actions</title> | ||
| <prolog> | ||
| <author>Radu Coravu</author> | ||
| <critdates> | ||
| <created date="2024-01-23"/> | ||
| </critdates> | ||
| </prolog> | ||
| <conbody> | ||
| <p>If you have a GitHub hosted DITA XML project (either on a private or public repository) | ||
| you can define GitHub actions to validate and publish your DITA XML project. </p> | ||
| <p>As an example the Oxygen XML Blog contains GitHub actions to validate and publish a DITA | ||
| XML project:<ul id="ul_mj4_j5t_21c"> | ||
| <li>Validate the entire DITA project using the Oxygen <xref | ||
| href="https://www.oxygenxml.com/doc/ug-editor/topics/scripting_oxygen_dita_validate_and_check_for_completeness.html" | ||
| format="html" scope="external"><b>Validate and Check for | ||
| Completeness</b></xref> command line script:<ul id="ul_xzd_n5t_21c"> | ||
| <li>Define in the GitHub project's <b>Settings->Secrets and | ||
| variables->Actions</b> category a variable named | ||
| <codeph>SCRIPTING_LICENSE_KEY</codeph> which has as value the Oxygen | ||
| scripting license key.</li> | ||
| <li>Set up a <xref | ||
| href="https://github.com/oxygenxml/blog/blob/master/build/build-validate-check.gradle" | ||
| format="gradle" scope="external">Gradle build file</xref> which | ||
| downloads an Oxygen all platforms kit, licenses it and runs it over the | ||
| DITA Map. The build file also applies an XSLT stylesheet over the XML | ||
| report to produce a Markdown report.</li> | ||
| <li>Create a <xref | ||
| href="https://github.com/oxygenxml/blog/blob/master/.github/workflows/validate-check-completion.yml" | ||
| format="yml" scope="external">GitHub action</xref> which is | ||
| triggered by pull requests or modifications done to pull requests, sets | ||
| up Java, calls the Gradle build file and then if there are errors | ||
| outputs the report in Markdown format using the | ||
| <codeph>$GITHUB_STEP_SUMMARY</codeph> variable. The report of | ||
| running such a GitHub action looks like this:<fig id="fig_dcp_3wt_21c"> | ||
| <image href="../images/validation-report-gh-action.png" | ||
| id="image_zf4_nvt_21c" scale="30"/> | ||
| </fig></li> | ||
| </ul></li> | ||
| </ul><ul id="ul_nvf_pvt_21c"> | ||
| <li>Validate only the changed topics in a pull request using <b>OpenAI</b> and a | ||
| custom prompt to check for example for grammar problems:<ul id="ul_u2m_rvt_21c"> | ||
| <li>Define in the GitHub project's <b>Settings->Secrets and | ||
| variables->Actions</b> category a variable named | ||
| <codeph>AI_LICENSE_KEY</codeph> which has as value the <b>OpenAI</b> | ||
| key.</li> | ||
| <li>Create a custom <xref | ||
| href="https://github.com/oxygenxml/blog/blob/master/build/build-validate-ai.gradle" | ||
| format="gradle" scope="external">Gradle build file</xref> which | ||
| finds all changed topics in the pull request and then uses the API key | ||
| to send the content to <b>OpenAI</b> asking for a report of changes in | ||
| <b>Markdown</b> format.</li> | ||
| <li>Create a <xref | ||
| href="https://github.com/oxygenxml/blog/blob/master/.github/workflows/ai-checks.yml" | ||
| format="yml" scope="external">custom GitHub action</xref> which | ||
| saves the list of changed files as an environmental variable and passes | ||
| this information to the build file, afterwards displaying the report | ||
| using the <codeph>$GITHUB_STEP_SUMMARY</codeph> variable. The report of | ||
| running such a GitHub action looks like this: <fig id="fig_pjb_mwt_21c"> | ||
| <image href="../images/validate-ai-gh-action.png" | ||
| id="image_kg3_nwt_21c" scale="40"/> | ||
| </fig></li> | ||
| </ul></li> | ||
| <li>Publish the Oxygen XML Blog DITA XML project to <b>Netlify</b> using a | ||
| <b>GitHub</b> action:<ul id="ul_jhk_qwt_21c"> | ||
| <li>Create an account on <xref href="https://www.netlify.com/" format="html" | ||
| scope="external">Netlify</xref> and create a site for the account. | ||
| Create an <xref | ||
| href="https://app.netlify.com/user/applications#personal-access-tokens" | ||
| format="html" scope="external">authentication token</xref> to be | ||
| able to access Netlify from a command line and deploy to the site from a | ||
| remote location. In the Netlify UI obtain the ID of <xref | ||
| href="https://app.netlify.com/sites/oxygenxmlblog/configuration/general#site-information" | ||
| format="html" scope="external">your site</xref>.</li> | ||
| <li>Define in the GitHub project's <b>Settings->Secrets and | ||
| variables->Actions</b> category two variables to keep the Netlify | ||
| authentication token and the side ID values. Create a secret also for | ||
| the <b>Oxygen Publishing Engine</b> license key.</li> | ||
| <li>Create a custom <xref | ||
| href="https://github.com/oxygenxml/blog/blob/master/build/build.gradle" | ||
| format="gradle" scope="external">Gradle build file</xref> which | ||
| downloads the <b>Oxygen Publishing Engine</b>, licenses it, produces the | ||
| output and stores it in a specific folder.</li> | ||
| <li>Create a custom <xref | ||
| href="https://github.com/oxygenxml/blog/blob/master/.github/workflows/publish.yml" | ||
| format="yml" scope="external">GitHub action</xref> which runs the | ||
| build file and then uses a plugin to upload the entire folder to the | ||
| Netlify web site. The end result looks like this: <xref | ||
| href="https://oxygenxmlblog.netlify.app/" format="html" | ||
| scope="external"/>.</li> | ||
| </ul></li> | ||
| </ul></p> | ||
| </conbody> | ||
| </concept> |