PublishToGitHubPages

This job template publishes HTML content from artifacts of other jobs to GitHub Pages.

Features

• Merge up to three artifacts into a single website: the documentation at the root, the code coverage report at /coverage and the static typing report at /typing.

• Deploy the result to GitHub Pages using GitHub’s deployment actions.

• Skip the deployment for pull_request events, so a pull-request cannot overwrite the published site.

• Optionally delete the GitHub Pages artifact afterwards.

Behavior

1. Download the HTML documentation artifact (doc).

2. Optionally download the code coverage report artifact into coverage/ (coverage).

3. Optionally download the static typing report artifact into typing/ (typing).

4. Delete a left-over GitHub Pages artifact from a previous run (pages).

5. Upload the merged directory as a GitHub Pages artifact (pages).

6. Deploy that artifact to GitHub Pages.

7. Delete the GitHub Pages artifact (cleanup).

Note

The job merges up to three artifacts into a single website: the documentation at the root, the code coverage report at /coverage and the static typing report at /typing.

Attention

Steps 5 to 7 are skipped for pull_request events, because a pull-request must not overwrite the published site. The repository’s GitHub Pages source has to be set to GitHub Actions.

Job Execution

Dependencies

• GitHub: pyTooling/download-artifact

  • GitHub: actions/download-artifact

• GitHub: actions/upload-pages-artifact

• GitHub: actions/deploy-pages

• GitHub: geekyeggo/delete-artifact

Instantiation

Simple Example

jobs:
  BuildTheDocs:
    # ...

  PublishToGitHubPages:
    uses: pyTooling/Actions/.github/workflows/PublishToGitHubPages.yml@r8
    needs:
      - BuildTheDocs
    with:
      doc: Documentation

Complex Example

jobs:
  PublishToGitHubPages:
    uses: pyTooling/Actions/.github/workflows/PublishToGitHubPages.yml@r8
    needs:
      - Params
      - BuildTheDocs
      - Coverage
      - StaticTypeCheck
    with:
      doc:      ${{ fromJson(needs.Params.outputs.artifact_names).documentation_html }}
      coverage: ${{ fromJson(needs.Params.outputs.artifact_names).codecoverage_html }}
      typing:   ${{ fromJson(needs.Params.outputs.artifact_names).statictyping_html }}

Parameter Summary

Goto input parameters

Parameter Name	Required	Type	Default
ubuntu_image_version	no	string	'26.04'
doc	yes	string	— — — —
coverage	no	string	''
typing	no	string	''
pages	no	string	'github-pages'
cleanup	no	string	'true'

Goto secrets

This job template needs no secrets.

Goto output parameters

Parameter Name	Type
github_pages_url	string

Input Parameters

ubuntu_image_version

Type:

string

Required:

no

Default Value:

'26.04'

Possible Values:

See actions/runner-images - Available Images for available Ubuntu image versions.

Description:

Version of the Ubuntu image used to run the job.

Note

Unfortunately, GitHub Actions has only a limited set of functions, thus, the usual Ubuntu image name like 'ubuntu-26.04' can’t be split into image name and image version.

doc

Type:

string

Required:

yes

Default Value:

— — — —

Possible Values:

Any valid artifact name.

Description:

Name of the documentation artifact containing the HTML website.

coverage

Type:

string

Required:

no

Default Value:

''

Possible Values:

Any valid artifact name.

Description:

Name of the coverage artifact containing the HTML coverage report, which will be integrated as a subdirectory.

typing

Type:

string

Required:

no

Default Value:

''

Possible Values:

Any valid artifact name.

Description:

Name of the type checking artifact containing the HTML type checker report, which will be integrated as a subdirectory.

pages

Type:

string

Required:

no

Default Value:

'github-pages'

Possible Values:

Any valid artifact name.

Description:

Name of the artifact handed to GitHub: actions/deploy-pages.
'github-pages' is the name GitHub’s Pages deployment expects and should only be changed if the artifact is consumed by something else.

cleanup

Type:

string

Required:

no

Default Value:

'true'

Possible Values:

'true' / 'false'

Description:

Delete the artifact named by pages after deployment.
'true' - delete the GitHub Pages artifact.
'false' - keep it.

Secrets

This job template needs no secrets.

Outputs

github_pages_url

Type:

string

Possible Values:

A URL, e.g. https://pytooling.github.io/Actions/.

Description:

URL of the deployed GitHub Pages site, as returned by GitHub: actions/deploy-pages.

Optimizations

This template offers no optimizations (reduced job runtime).