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@latest
It 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@latest
If 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: true
The 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@latest
Here are a few common workflow scenarios.
steps:
- uses: retypeapp/action-build@latest
If 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_docs
Or the full path (relative to the repository root) to retype.yml
- uses: retypeapp/action-build@latest
with:
config: my_docs/retype.yml
The config file may have a different file name
- uses: retypeapp/action-build@latest
with:
config: my_docs/retype-staging.json
In 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.yml
It 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: true
You 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-here
Return 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