Edit online

Building, Validating, and Publishing Using GitHub Actions

Radu Coravu
23 Jan 2024
Read time: 6 minute(s)

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.

As an example, the Oxygen XML Blog contains GitHub actions to validate and publish a DITA XML project:
  • Publish the Oxygen XML Blog DITA XML project to Netlify using a GitHub action:
    1. Create an account on Netlify and create a site for the account. Create an authentication token 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 your site.
    2. In the GitHub project's Settings->Secrets and variables->Actions category, define two variables to keep the Netlify authentication token and the side ID values. Also, create a secret for the Oxygen Publishing Engine license key.
    3. Create a custom Gradle build file that downloads the Oxygen Publishing Engine, licenses it, produces the output, and stores it in a specific folder.
    4. Create a custom GitHub action that 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: https://oxygenxmlblog.netlify.app/.
  • Publish the DITA XML project to an Amazon S3 server using a GitHub action:
    1. Create an Amazon S3 bucket and configure it for static website hosting. Make note of the bucket name and region.
    2. In the IAM console, create a new user with programmatic access and attach a policy that grants write access to the S3 bucket. Obtain the access key ID and secret access key for this user.
    3. In the GitHub project's Settings->Secrets and variables->Actions category, define variables to store the S3 bucket name, region, access key ID, and secret access key. Also, create a secret for the Oxygen Publishing Engine license key.
    4. Create a custom Gradle build file that downloads the Oxygen Publishing Engine, licenses it, produces the output, and stores it in a specific folder.
    5. Create a GitHub action that runs the build file and then uses the aws-actions/configure-aws-credentials action to configure the AWS credentials, followed by the aws-actions/s3-sync action to sync the output folder with the S3 bucket.
  • Validate the entire DITA project using the Oxygen Validate and Check for Completeness command-line script:
    1. In the GitHub project's Settings->Secrets and variables->Actions category, define a variable named SCRIPTING_LICENSE_KEY that has the Oxygen scripting license key as its value.
    2. Set up a Gradle build file that 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.
    3. Create a GitHub action that 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 $GITHUB_STEP_SUMMARY variable. The report of running such a GitHub action contains the severity, description, and a link to the topic where the error was found. The link can be followed to open the topic in Oxygen XML Web Author:
  • Validate only the changed topics in a pull request using OpenAI and a custom prompt to check for grammar problems:
    1. In the GitHub project's Settings->Secrets and variables->Actions category, define a variable named AI_LICENSE_KEY that has the OpenAI key as its value.
    2. Create a custom Gradle build file that finds all changed topics in the pull request and then uses the API key to send the content to OpenAI asking for a report of changes in Markdown format.
    3. Create a custom GitHub action that saves the list of changed files as an environmental variable and passes this information to the build file, afterwards displaying the report using the $GITHUB_STEP_SUMMARY variable. The report of running such a GitHub action looks like this: