Autogenerate docs for actions

3lvia · Mar 26, 2024 · 454a2a5 · 454a2a5
1 parent d6215ae
commit 454a2a5
Show file tree

Hide file tree

Showing 9 changed files with 72 additions and 139 deletions.
diff --git a/.github/workflows/build-deploy.yml b/.github/workflows/build-deploy.yml
@@ -22,6 +22,7 @@ jobs:
   unittests:
     name: Unit Tests
     runs-on: ubuntu-latest
+    if: false
     steps:
       - name: Checkout repository
         uses: actions/checkout@v4
@@ -31,6 +32,7 @@ jobs:
   analyze:
     name: Analyze
     runs-on: ubuntu-latest
+    if: false
     steps:
       - name: Checkout repository
         uses: actions/checkout@v4
@@ -41,6 +43,7 @@ jobs:
     name: Build and Scan
     runs-on: ubuntu-latest
     environment: build
+    if: false
     steps:
       - name: Checkout repository
         uses: actions/checkout@v4
@@ -57,6 +60,7 @@ jobs:
     needs: [build, analyze]
     runs-on: ubuntu-latest
     environment: dev
+    if: false
     steps:
       - name: Checkout repository
         uses: actions/checkout@v4
@@ -74,6 +78,7 @@ jobs:
     needs: [build, analyze]
     runs-on: ubuntu-latest
     environment: dev
+    if: false
     steps:
       - name: Checkout repository
         uses: actions/checkout@v4

diff --git a/.github/workflows/check-format.yml b/.github/workflows/check-format.yml
@@ -8,6 +8,7 @@ jobs:
   prettier_check:
     name: 'Prettier check'
     runs-on: ubuntu-latest
+    if: false
     steps:
       - name: Checkout repository
         uses: actions/checkout@v4

diff --git a/.github/workflows/generate-docs.yml b/.github/workflows/generate-docs.yml
@@ -0,0 +1,33 @@
+name: Generate action documentation
+
+on:
+  push:
+    branches: [trunk]
+
+jobs:
+  generate_docs:
+    name: Generate action documentation for ${{ matrix.action-file }}
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        action-file:
+          - 'build/action.yml'
+          - 'deploy/action.yml'
+          - 'trivy-iac-scan/action.yml'
+          - 'terraform-format/action.yml'
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Generate documentation
+        uses: npalm/[email protected]
+        with:
+          sourceFile: ${{ matrix.action-file }}
+
+      - name: Commit changes
+        run: |
+          git config user.name github-actions
+          git config user.email [email protected]
+          git add .
+          git commit -m "Update action documentation for ${{ matrix.action-file }}"
+          git push
diff --git a/README.md b/README.md
@@ -1,10 +1,9 @@
 # core-github-actions-templates
 
-## Build and Deploy
+<!-- action-docs-header source="build/action.yml" project="core-github-actions-templates" version="trunk" -->
+<!-- action-docs-description source="build/action.yml" project="core-github-actions-templates" version="trunk" -->
 
-To use the build and deploy actions, you must first add your Github repository to https://github.com/3lvia/github-repositories-terraform.
-
-### Example
+### Example usage in a full workflow
 
 ```yaml
 name: Build and Deploy to Kubernetes
@@ -98,124 +97,23 @@ jobs:
           AZURE_CLIENT_ID: ${{ vars.AKS_CLIENT_ID }}
           helmValuesPath: '.github/deploy/values.yaml'
 ```
-
-### Build
-
-Template that builds Docker image, scans for vulnerabilities and uploads to Azure Container Registry.
-
-### Inputs
-
-| Name                          | Type    | Required | Default                 | Description                                                                                                                                            |
-| ----------------------------- | ------- | -------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `name`                        | String  | yes      |                         | Name of application.                                                                                                                                   |
-| `namespace`                   | String  | yes      |                         | Namespace of application.                                                                                                                              |
-| `dockerfile`                  | String  | yes      |                         | Path to Dockerfile.                                                                                                                                    |
-| `dockerBuildContext`          | String  |          | directory of Dockerfile | Path to Docker build context.                                                                                                                          |
-| `severity`                    | String  |          | `CRITICAL,HIGH`         | Severity levels to scan for. See https://github.com/aquasecurity/trivy-action?tab=readme-ov-file#inputs for more information.                          |
-| `trivy-cve-ignores`           | String  |          |                         | Comma-separated list of CVEs for Trivy to ignore. See https://aquasecurity.github.io/trivy/v0.49/docs/configuration/filtering/#trivyignore for syntax. |
-| `trivy-enable-secret-scanner` | Boolean |          | `true`                  | Enable Trivy secret scanner.                                                                                                                           |
-| `trivy-skip-dirs`             | String  |          |                         | Directories/files skipped by Trivy. See https://github.com/aquasecurity/trivy-action?tab=readme-ov-file#inputs for more information.                   |
-| `AZURE_CLIENT_ID`             | String  | yes      | Elvia default AKS       | ClientId of a service principal that can push to Container Registry.                                                                                   |
-| `AZURE_TENANT_ID`             | String  |          | Elvia Tenant            | TenantId of a service principal that can push to Azure Container Registry.                                                                             |
-| `ACR_SUBSCRIPTION_ID`         | String  |          | Elvia default ACR       | Subscription ID of the Azure Container Registry to push to.                                                                                            |
-| `ACR_NAME`                    | String  |          | Elvia default ACR       | Name of the Azure Container Registry to push to.                                                                                                       |
-
-### Deploy
-
-Template that deploys an Elvia Helm chart to Kubernetes
-
-### Inputs
-
-| Name                            | Type    | Required            | Default                      | Description                                                                                                                      |
-| ------------------------------- | ------- | ------------------- | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
-| `name`                          | String  | yes                 |                              | Name of application.                                                                                                             |
-| `namespace`                     | String  | yes                 |                              | Namespace of application.                                                                                                        |
-| `environment`                   | String  | yes                 |                              | Environment to deploy to. `dev`, `test` or `prod`.                                                                               |
-| `helmValuesPath`                | String  |                     | `.github/deploy/values.yaml` | Path to Helm values file, relative to the root of the repository.                                                                |
-| `checkout`                      | Boolean |                     | `true`                       | If true, the action will check out the repository. If false, the action will assume the repository has already been checked out. |
-| `runtimeCloudProvuider`         | String  |                     | `AKS`                        | Kubernetes cloud provider to deploy to: 'AKS' or 'GKE'. Defaults to 'AKS'.                                                       |
-| `AZURE_CLIENT_ID`               | String  | only for AKS deploy |                              | ClientId of a service principal that has access to AKS. Only required for deploying to AKS.                                      |
-| `AZURE_TENANT_ID`               | String  |                     | Elvia Tenant                 | TenantId of a service principal that has access to AKS.                                                                          |
-| `AKS_SUBSCRIPTION_ID`           | String  |                     | Elvia default AKS            | Subscription ID of the AKS cluster to deploy to.                                                                                 |
-| `AKS_CLUSTER_NAME`              | String  |                     | Elvia default AKS            | Name of the AKS cluster to deploy to.                                                                                            |
-| `AKS_RESOURCE_GROUP`            | String  |                     | Elvia default AKS            | Resource group of the AKS cluster to deploy to.                                                                                  |
-| `GC_SERVICE_ACCOUNT`            | String  | only for GKE deploy |                              | Service account to use for deploying to GKE. Only required for deploying to GKE.                                                 |
-| `GC_WORKLOAD_IDENTITY_PROVIDER` | String  | only for GKE deploy | `gcp`                        | Workload identity provider to use for deploying to GKE. Only required for deploying to GKE.                                      |
-| `GC_PROJECT_ID`                 | String  |                     | Elvia default GKE            | Project ID of the GKE cluster to deploy to. Defaults to Elvias normal clusters.                                                  |
-| `GC_CLUSTER_NAME`               | String  |                     | Elvia default GKE            | Name of the GKE cluster to deploy to. Defaults to Elvias normal clusters.                                                        |
-| `GC_CLUSTER_LOCATION`           | String  |                     | Elvia default GKE            | Location of the GKE cluster to deploy to. Defaults to Elvias normal clusters.                                                    |
-
-## Trivy IaC scanning
-
-Uses https://github.com/aquasecurity/trivy-action to scan IaC and report security issues.
-The action will report any vulnerabilities to GitHub Advanced Security, which will be visible in the Security tab on GitHub.
-
-### Inputs
-
-| Name            | Type    | Required | Default                            | Description                                                                                                                      |
-| --------------- | ------- | -------- | ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
-| `path`          | String  | no       | `.`                                | Path to IaC to scan.                                                                                                             |
-| `skip-dirs`     | String  | no       |                                    | Comma-separated list of directories to skip                                                                                      |
-| `severity`      | String  | no       | `CRITICAL,HIGH,MEDIUM,LOW,UNKNOWN` | Severity levels to scan for. See https://github.com/aquasecurity/trivy-action?tab=readme-ov-file#inputs for more information.    |
-| `upload-report` | Boolean | no       | `true`                             | Upload Trivy report to GitHub Security tab.                                                                                      |
-| `checkout`      | Boolean | no       | `true`                             | If true, the action will check out the repository. If false, the action will assume the repository has already been checked out. |
-
-### Example
-
-```yaml
-name: Scan IaC with Trivy
-on:
-  push:
-    branches: [develop, master]
-  pull_request:
-    branches: [develop, master]
-  schedule:
-    - cron: '1 2 * * 3' # every Wednesday at 02:01
-
-jobs:
-  trivy_scan:
-    runs-on: ubuntu-latest
-    name: 'Scan IaC with Trivy'
-    permissions:
-      actions: read
-      contents: read
-      security-events: write
-    steps:
-      - uses: 3lvia/core-github-actions-templates/trivy-iac-scan@trunk
-        with:
-          path: 'terraform'
-          skip-dirs: 'terraform/modules'
-```
-
-## Terraform format
-
-Uses built-in formatter for Terraform CLI to check format of Terraform code.
-
-### Inputs
-
-| Name       | Type    | Required | Default | Description                                                                                                                      |
-| ---------- | ------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------------- |
-| `path`     | String  | no       | `.`     | Path to process.                                                                                                                 |
-| `checkout` | Boolean | no       | `true`  | If true, the action will check out the repository. If false, the action will assume the repository has already been checked out. |
-
-### Example
-
-```yaml
-name: Check Terraform code formatting
-
-on:
-  pull_request:
-    branches: [develop]
-
-jobs:
-  terraform_format_check:
-    permissions:
-      contents: read
-    steps:
-      - uses: 3lvia/core-github-actions-templates/terraform-format@trunk
-        with:
-          path: 'terraform'
-```
+<!-- action-docs-inputs source="build/action.yml" project="core-github-actions-templates" version="trunk" -->
+<!-- action-docs-usage source="build/action.yml" project="core-github-actions-templates" version="trunk" -->
+
+<!-- action-docs-header source="deploy/action.yml" project="core-github-actions-templates" version="trunk" -->
+<!-- action-docs-description source="deploy/action.yml" project="core-github-actions-templates" version="trunk" -->
+<!-- action-docs-inputs source="deploy/action.yml" project="core-github-actions-templates" version="trunk" -->
+<!-- action-docs-usage source="deploy/action.yml" project="core-github-actions-templates" version="trunk" -->
+
+<!-- action-docs-header source="trivy-iac-scan/action.yml" project="core-github-actions-templates" version="trunk" -->
+<!-- action-docs-description source="trivy-iac-scan/action.yml" project="core-github-actions-templates" version="trunk" -->
+<!-- action-docs-inputs source="trivy-iac-scan/action.yml" project="core-github-actions-templates" version="trunk" -->
+<!-- action-docs-usage source="trivy-iac-scan/action.yml" project="core-github-actions-templates" version="trunk" -->
+
+<!-- action-docs-header source="terraform-format/action.yml" project="core-github-actions-templates" version="trunk" -->
+<!-- action-docs-description source="terraform-format/action.yml" project="core-github-actions-templates" version="trunk" -->
+<!-- action-docs-inputs source="terraform-format/action.yml" project="core-github-actions-templates" version="trunk" -->
+<!-- action-docs-usage source="terraform-format/action.yml" project="core-github-actions-templates" version="trunk" -->
 
 # Development
 

diff --git a/analyze/action.yml b/analyze/action.yml
@@ -1,5 +1,5 @@
-name: Analyze
-description: Run CodeQL
+name: 'Analyze'
+description: 'Run CodeQL analysis.'
 
 runs:
   using: 'composite'

diff --git a/build/action.yml b/build/action.yml
@@ -1,17 +1,18 @@
-name: Build and Scan
-description: Build Docker image and scan for vulnerabilities
+name: 'Build'
+description: 'Builds Docker image, scans for vulnerabilities using Trivy and pushes to Azure Container Registry. To use the `Build` and `Deploy` actions, you must first add your Github repository to https://github.com/3lvia/github-repositories-terraform.'
 inputs:
   name:
     description: 'Name of application. Do not include namespace.'
     required: true
+    default: halloj
   namespace:
     description: 'Namespace or system of the application.'
     required: true
   dockerfile:
     description: 'Path to Dockerfile.'
     required: true
   dockerBuildContext:
-    description: 'Docker build context. It is the working directory needed to build the dockerfile. Defaults to the directory with the Dockerfile.'
+    description: 'Docker build context, which is the working directory needed to build the dockerfile. Defaults to the directory of the Dockerfile.'
     required: false
   severity:
     description: 'Severity levels to scan for. See https://github.com/aquasecurity/trivy-action?tab=readme-ov-file#inputs for more information.'
@@ -27,16 +28,15 @@ inputs:
   trivy-skip-dirs:
     description: 'Directories/files skipped by Trivy. See https://github.com/aquasecurity/trivy-action?tab=readme-ov-file#inputs for more information.'
     required: false
-    default: ''
   AZURE_CLIENT_ID:
     description: 'ClientId of a service principal that can push to Container Registry.'
     required: true
   AZURE_TENANT_ID:
-    description: "TenantId of a service principal that can push to Azure Container Registry. Default to Elvia's Tenant ID"
+    description: "TenantId of a service principal that can push to Azure Container Registry. Default to Elvia's Tenant ID."
     required: false
     default: '2186a6ec-c227-4291-9806-d95340bf439d'
   ACR_SUBSCRIPTION_ID:
-    description: "Subscription ID of the Azure Container Registry to push to. Defaults to Elvia's standard ACR."
+    description: "Subscription ID of the Azure Container Registry to push to. Defaults to subscription ID of Elvia's standard ACR."
     required: false
     default: '9edbf217-b7c1-4f6a-ae76-d046cf932ff0'
   ACR_NAME:

diff --git a/deploy/action.yml b/deploy/action.yml
@@ -1,6 +1,5 @@
-name: Deploy to kubernetes
-description: 'Deploys an application to Kubernetes using the Elvia Helm chart'
-
+name: 'Deploy'
+description: 'Deploys an application to Kubernetes using the Elvia Helm chart. To use the `Build` and `Deploy` actions, you must first add your Github repository to https://github.com/3lvia/github-repositories-terraform.'
 inputs:
   name:
     description: 'Name of application. Do not include namespace.'
@@ -33,15 +32,12 @@ inputs:
   AKS_SUBSCRIPTION_ID:
     description: 'Subscription ID of AKS to deploy to. Defaults to Elvias normal clusters.'
     required: false
-    default: ''
   AKS_CLUSTER_NAME:
     description: 'Name of the AKS cluster to deploy to. Defaults to Elvias normal clusters.'
     required: false
-    default: ''
   AKS_RESOURCE_GROUP:
     description: 'Resource group of the AKS cluster to deploy to. Defaults to Elvias normal clusters.'
     required: false
-    default: ''
   GC_SERVICE_ACCOUNT:
     description: 'Service account to use for deploying to GKE. Only required for deploying to GKE.'
     required: false

diff --git a/terraform-format/action.yml b/terraform-format/action.yml
@@ -1,5 +1,5 @@
-name: Terraform format
-description: 'Checks formatting of Terraform files.'
+name: 'Terraform format check'
+description: 'Uses the built-in formatter from the Terraform CLI to check the format of Terraform code.'
 inputs:
   path:
     description: 'Path to process.'

diff --git a/trivy-iac-scan/action.yml b/trivy-iac-scan/action.yml
@@ -1,5 +1,5 @@
 name: Trivy IaC scan
-description: 'Scan IaC with Trivy and report to GitHub Advanced Security.'
+description: 'Uses https://github.com/aquasecurity/trivy-action to scan IaC and report security issues. The action will report any vulnerabilities to GitHub Advanced Security, which will be visible in the Security tab on GitHub.'
 inputs:
   path:
     description: 'Path to the directory containing the IaC files.'