A GitHub Action to build a Retype powered website. The output of this action is then made available to subsequent workflow steps, such as publishing to GitHub Pages using the retypeapp/action-github-pages action.
This action runs retype build over the files in a repository to build a website in the form of a static html website that can be published to any website hosting solution available.
After the action completes, it will export the retype-output-path value for the next steps to handle the output. The output files can then be pushed back to GitHub, or sent by FTP to another web server, or any other form of website publication target.
This action will look for a retype.yml file in the repository root.
steps:
- uses: actions/checkout@v3
- uses: retypeapp/action-build@latestIt may be useful to include the actions/setup-dotnet step before retypeapp/action-build@latest. With this, the Build Action can install the dotnet tool Retype package.
The workflow file above would then become:
steps:
- uses: actions/checkout@v3
- uses: actions/setup-dotnet@v1
with:
dotnet-version: 7.0.x
- uses: retypeapp/action-build@latestIf this is not included though, the action will still work, but it may need to use the NPM package in case the installed .NET version is not the one required by Retype. When resorting to the NPM package it may take a bit longer to set up the workflow due to the larger download size. It may also be the case that the GitHub runner is an unsupported OS by the NPM packages; as long as it has .NET installed, Retype should work regardless of the OS. But the NPM package is built targetted to specific OS'es, namely Linux, Mac and Windows.
Configuration of the project should be done in the projects retype.yml file.
Specifies the path where retype.yml file should be located or path to the specific configuration file.
Specifies the license key to be used with Retype.
- uses: retypeapp/action-build@latest
with:
license: ${{ secrets.RETYPE_LICENSE_KEY }}NOTICE: The license key value cannot be saved directly to your configuration file. To pass the license key to Retype during the build process, the value must be passed as a GitHub Secret. For information on how to store a secret on your repository or organization, see RETYPE_SECRET docs.
This config is Retype !badge PRO only.
To enable --strict mode during build. Return a non-zero exit code if the build had errors or warnings.
- uses: retypeapp/action-build@latest
with:
strict: trueThe following workflow will serve as our starting template for most of the samples below.
name: GitHub Action for Retype
on:
workflow_dispatch:
push:
branches:
- main
jobs:
publish:
runs-on: ubuntu-latest
permissions:
contents: write
steps:
- uses: actions/checkout@v3
- uses: retypeapp/action-build@latestHere are a few common workflow scenarios.
steps:
- uses: retypeapp/action-build@latestIf a license key is required, please configure using a GitHub Secret.
- uses: retypeapp/action-build@latest
with:
license: ${{ secrets.RETYPE_LICENSE_KEY }}For more information on how to set up and use secrets in GitHub actions, see Encrypted secrets.
It is possible to point the directory where retype.yml is:
- uses: retypeapp/action-build@latest
with:
config: my_docsOr the full path (relative to the repository root) to retype.yml
- uses: retypeapp/action-build@latest
with:
config: my_docs/retype.ymlThe config file may have a different file name
- uses: retypeapp/action-build@latest
with:
config: my_docs/retype-staging.jsonIn a bit more complex scenario where various repositories are checked out in a workflow. This may be useful, for instance, if retype documentation is generated from files across different repositories.
- uses: actions/checkout@v3
with:
path: own-repository
- uses: actions/checkout@v3
with:
repository: organization/repository-name
path: auxiliary-repository
- uses: retypeapp/action-build@latest
with:
config: own-repository/my_docs/retype.ymlIt is possible to get the output path of this step to use in other steps or actions after the action-build is complete by using the retype-output-path value.
- uses: retypeapp/action-build@latest
id: build1
- shell: bash
env:
MY_ENV_TO_RETYPE_PATH: ${{ steps.build1.outputs.retype-output-path }}
run: echo "Retype output is available at '${MY_ENV_TO_RETYPE_PATH}'."Other Retype actions within the workflow may consume the output of this action by using the RETYPE_OUTPUT_PATH environment variable.
It is required to upload the output with actions/upload-artifact, as changes in the file system are not available across different GitHub action jobs. Then from the subsequent job(s), the artifact can be retrieved using the download-artifact action.
The following sample demonstrates the upload-artifact and download-artifact actions.
To use the Retype output in another job within the same workflow, or let an external source download it, it is possible to use actions/upload-artifact to persist the files. The uploaded artifact can then be retrieved in another job or workflow using actions/download-artifact
- uses: retypeapp/action-build@latest
id: build1
- uses: actions/upload-artifact@v2
with:
path: ${{ steps.build1.outputs.retype-output-path }}By using the Retype retypeapp/action-github-pages action, the workflow can publish the output to a branch, or directory, or even a make a Pull Request. The website can then be hosted using GitHub Pages.
The following sample demonstrates configuring the Retype action-github-pages action to publish to GitHub Pages:
- uses: retypeapp/action-build@latest
- uses: retypeapp/action-github-pages@latest
with:
branch: retype
update-branch: trueYou can test with a specific branch of the retypapp action by replacing the @latest with the @branch-name-here.
- uses: retypeapp/action-build@branch-name-hereReturn a non-zero exit code if the build had errors or warnings. Set true to enable stict mode.
- uses: retypeapp/action-build@latest
with:
strict: true