Skip to content

Lighthouse Hub Github Actions

Github Actions that help teams use the Lighthouse Hub

TechDocs Action

This action creates a Kubernetes Job that will generate and publish your TechDocs for the Lighthouse Hub.

Overview

The Kubernetes Job consists of two containers: a git-sync container and a TechDocs container. The git-sync container is an initContainer that pulls a git repository to a shared volume so the TechDocs container has a copy of all markdown files. The TechDocs container then uses the TechDocs-cli to generate and publish your documentation to the Lighthouse S3 bucket.

TechDocs Prerequisites

The root directory of your repository contains:

More info about Entity Descriptor files

Usage

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
- name: Create TechDocs Job
  uses: department-of-veterans-affairs/lighthouse-github-actions/.github/actions/techdocs-webhook@latest
  with:
    # Owner and repository where the documentation lives (e.g. department-of-veterans-affairs/lighthouse-developer-portal)
    # Default: ${{ github.repository }}
    repository: ''

    # Repo branch to validate/publish documentation; use ${{ github.ref_name }} to specify the branch used for the workflow dispatch
    # Defaults to repository's default branch
    branch: ''

    # Name of Entity descriptor file; used to create Entity path (i.e. namespace/kind/name)
    # Default: 'catalog-info.yaml'
    descriptor-file: ''

    # Personal Access Token used for TechDocs Webhook
    # Scopes: Repo
    token: ''

    # Deploy to gh-pages; only include if you want to publish docs externally to GitHub (github.io)
    # Default: false
    gh-pages: true|false

    # Flag for enabling/disabling TechDocs for production
    # Default: true
    enable-production: true|false

Examples

Create standalone workflow with Github Actions

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
# Example workflow
name: Publish Documentation
on:
  push:
    branches: [main]
    paths: ['**/docs/*', '**/mkdocs.yaml'] # Additionally, using '**/*.md' will check all '.md' files for changes including in /docs
jobs:
  create-techdocs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Techdocs webhook
        uses: department-of-veterans-affairs/lighthouse-github-actions/.github/actions/techdocs-webhook@main
        with:
          repository: ${{ github.repository }}
          token: ${{ secrets.PAT }}
          branch: ${{ github.ref_name }}