Skip to content

Latest commit

 

History

History
152 lines (113 loc) · 6.8 KB

README.md

File metadata and controls

152 lines (113 loc) · 6.8 KB
Raw

Shareableviz Action

Overview

A GitHub action which deploys your Kedro-Viz static site on GitHub pages. This action helps in the automation of a deployment startegy mentioned in platform agnostic sharing with Kedro-Viz

Prerequisites

  • GitHub Pages Setup: Configure your repository for GitHub Pages.
  • Kedro-project dependencies: Install all the Kedro-project dependencies before using this action in your workflow
  • Python-version: You need to have an environment with python>=3.9 in your workflow

NOTE: While configuring your repository for GitHub Pages, you have two publishing source options. You can either choose a branch or a custom GitHub Actions workflow. If you choose a branch, the build artifacts will be uploaded to the publish_branch you pass as an input to the action, which defaults to gh-pages. If you choose a custom GitHub Actions workflow, you need to mention that in the input publishing_source to the action and no artifacts/branch will be created. Please find more information on configuring a publishing source for github pages site in the official docs.

Usage

- uses: ravi-kumar-pilla/shareableviz-action@v1
  with:
    # The GitHub token to authenticate deployment. This is autogenerated by the action.
    # Default: ${{ github.token }}
    github_token: ''

    # The Kedro-project path to build the Kedro-Viz artifacts.
    # Default: '.'
    project_path: ''
    
    # Your consent to participate in Kedro-Telemetry.
    # Default: true
    telemetry_consent: ''

    # The python version used for the deployment. This should be `>=3.9`
    # Default: '3.11'
    python_version: ''

    # The publishing source for GitHub pages. This can be either 
    # 'branch' or 'workflow' based on your GitHub Pages configuration
    # Default: 'branch'
    publishing_source: ''

    # The GitHub pages publish branch to upload the artifacts 
    # if your publishing_source is a branch
    # Default: 'gh-pages'
    publish_branch: ''

    # The commit message for the deployment, if your publishing_source is a branch.
    # Defaults to your original commit message.
    # Default: ${{ github.event.head_commit.message }}
    commit_message: ''

    # The git config user.name or the owner of the commit.
    # if your publishing_source is a branch.
    # Default: 'github-actions[bot]'
    user_name: ''

    # The git config user.email or the email of the commit owner.
    # if your publishing_source is a branch.
    # Default: 'github-actions[bot]@users.noreply.github.com'
    user_email: ''

Configure the action

  1. Adding the GitHub Action to your workflow:

    1. Create a workflow file in your repository: .github/workflows/shareableviz.yml
    2. Add the following code to the workflow file:
        # An example workflow configuration

    # The name of your workflow
    name: Publish and share Kedro Viz 
    
    permissions:
        
        # The contents permission is required to use the action 
        # if your GitHub publishing source is a branch
        contents: write 
        
        # The pages and id-token permissions are required to use 
        # the action if your GitHub publishing source is a custom 
        # GitHub Actions workflow
        pages: write 
        id-token: write
    
    on: 
        # This can be configured based on your requirements 
        # (i.e., the workflow trigger condition)
        pull_request:
        push:
            branches:
                - main
        workflow_dispatch:

    # We mentioned the minimal jobs for the workflow
    jobs: 
        deploy:
            # The action is currently tested on ubuntu-latest (Recommended)
            runs-on: ubuntu-latest 
            steps:
                - name: Fetch the repository
                  uses: actions/checkout@v4
                - name: Set up Python
                  uses: actions/setup-python@v5
                  with:
                    # Requires python >= 3.9
                    python-version: 3.11 
                  # This installs the Kedro-project dependencies
                - name: Install Project Dependencies
                  run: |
                    python -m pip install --upgrade pip
                    # This is not required if your Kedro Project 
                    # is at the root of your GitHub Repository
                    cd demo-project 
                    pip install -r requirements.txt
                  # Using the action
                - name: Deploy Kedro-Viz to GH Pages 
                  uses: ravi-kumar-pilla/shareableviz-action@v1
                  with:
                    # This is not required if your Kedro Project 
                    # is at the root of your GitHub Repository
                    project_path: 'demo-project'

Test the action

After you've completed the configuration, trigger the workflow as per the workflow trigger condition.

  • The GitHub workflow Publish and share Kedro Viz should start. You can find it in the Actions tab with your commit message.
  • Once the workflow is successfully completed, the artifacts of your Kedro-Viz static site will be uploaded to the publish-branch input specified to the action if your GitHub pages publishing source is branch.
  • If your GitHub pages publishing source is a custom GitHub Actions workflow, you need to select the above workflow .github/workflows/shareableviz.yml as the source.
  • You can access the static site at http://<username>.github.io/<repo-name>

Credits

The list of third party actions used in this project, with due credits to their authors and license terms. More details can be found inside the folder of each action.

Deploy to GitHub Pages when publishing source is a branch

We use the GitHub action peaceiris/actions-gh-pages to deploy the static site to a publish branch which is released under MIT license.

Deploy to GitHub Pages when publishing source is a custom GitHub Action Workflow

We use the GitHub actions actions/upload-pages-artifact and actions/deploy-pages which are released under MIT license.

License

shareableviz-action is licensed under the Apache 2.0 License.