Merge pull request #1 from Dirrk/feat/initial-setup

initial code

.github/workflows/pull_request.yml

@@ -0,0 +1,38 @@
+name: Pull Request actions
+on:
+  - pull_request
+jobs:
+
+  label:
+    name: 'PR Labeler'
+    if: github.event.action == 'opened'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: TimonVS/pr-labeler-action@v3
+        with:
+          configuration-path: .github/pr-labeler.yml
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+  build:
+    name: 'Build example docs'
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v2
+      with:
+        ref: ${{ github.event.pull_request.head.ref }}
+
+    - name: Should generate README.md for test_a
+      uses: ./
+      with:
+        action_docs_working_dir: examples/test_a
+        action_docs_git_push: 'false'
+
+    - name: Should generate README.md for test_b
+      uses: ./
+      with:
+        action_docs_working_dir: examples/test_b
+        action_docs_git_push: 'false'
+
+    - name: Generate this repos README.md
+      uses: ./

Dockerfile

@@ -0,0 +1,12 @@
+FROM alpine:3.10
+
+RUN set -x \
+  && apk add --no-cache bash sed jq curl git wget \
+  && wget -O gomplate https://github.com/hairyhenderson/gomplate/releases/download/v3.6.0/gomplate_linux-amd64 \
+  && chmod 755 gomplate \
+  && mv gomplate /usr/local/bin/gomplate \
+  && mkdir -p /src
+
+COPY src /src/
+
+ENTRYPOINT ["/src/docker-entrypoint.sh"]

README.md

@@ -1,2 +1,19 @@
 # action-docs
 Github action that generates docs for a github action and injects them into the README.md
+
+<!--- BEGIN_ACTION_DOCS --->
+## Inputs
+
+| Name | Description | Default | Required |
+|------|-------------|---------|----------|
+| action\_docs\_git\_commit\_message | Commit message | action-docs: automated action | false |
+| action\_docs\_git\_push | If true it will commit and push the changes | true | false |
+| action\_docs\_template\_file | Template file to use for rendering the markdown docs | /src/default\_template.tpl | false |
+| action\_docs\_working\_dir | Directory that contains the action.yml and README.md | . | false |
+
+## Outputs
+
+| Name | Description |
+|------|-------------|
+| num\_changed | Number of files changed |
+<!--- END_ACTION_DOCS --->

action.yml

@@ -0,0 +1,32 @@
+name: action-docs
+author: Derek Rada
+description: Github action that generates docs for a github action and injects them into the README.md
+inputs:
+  action_docs_working_dir:
+    description: Directory that contains the action.yml and README.md
+    required: false
+    default: '.'
+  action_docs_template_file:
+    description: Template file to use for rendering the markdown docs
+    required: false
+    default: '/src/default_template.tpl'
+  action_docs_git_push:
+    description: If true it will commit and push the changes
+    required: false
+    default: 'true'
+  action_docs_git_commit_message:
+    description: Commit message
+    required: false
+    default: 'action-docs: automated action'
+
+outputs:
+  num_changed:
+    description: Number of files changed
+
+runs:
+  using: docker
+  image: Dockerfile
+
+branding:
+  icon: file-text
+  color: gray-dark

examples/test_a/README.md

@@ -0,0 +1,27 @@
+# terraform-docs
+A Github action for generating terraform module documentation using terraform-docs and gomplate.
+
+# Configuration
+<!--- BEGIN_ACTION_DOCS --->
+## Inputs
+
+| Name | Description | Default | Required |
+|------|-------------|---------|----------|
+| tf\_docs\_args | Additional args to pass | --sort-inputs-by-required | false |
+| tf\_docs\_atlantis\_file | Generate directories by parsing an atlantis formatted yaml to enable provide the file name to parse (eg atlantis.yaml) (disabled by default) | disabled | false |
+| tf\_docs\_content\_type | Generate document or table | table | false |
+| tf\_docs\_find\_dir | Generate directories by running find ./tf\_docs\_find\_dir -name \*.tf (disabled by default) | disabled | false |
+| tf\_docs\_git\_commit\_message | Commit message | terraform-docs: automated action | false |
+| tf\_docs\_git\_push | If true it will commit and push the changes | false | false |
+| tf\_docs\_indention | Indention level of Markdown sections [1, 2, 3, 4, 5] (default 2) | 2 | false |
+| tf\_docs\_output\_file | File in module directory where the docs should be placed | USAGE.md | false |
+| tf\_docs\_output\_method | Method should be one of (replace/inject/print) where replace will replace the tf\_docs\_output\_file, inject will inject the content between start and close delims and print will just print the output | inject | false |
+| tf\_docs\_template | When provided will be used as the template if/when the OUTPUT\_FILE does not exist | # Usage<br><!--- BEGIN\_TF\_DOCS ---><br><!--- END\_TF\_DOCS ---><br> | false |
+| tf\_docs\_working\_dir | Directories of terraform modules to generate docs for seperated by commas (conflicts with atlantis/find dirs) | . | false |
+
+## Outputs
+
+| Name | Description |
+|------|-------------|
+| num\_changed | Number of files changed |
+<!--- END_ACTION_DOCS --->

examples/test_a/action.yml

@@ -0,0 +1,63 @@
+name: terraform-docs
+author: Derek Rada
+description: A Github action for generating terraform module documentation using terraform-docs and gomplate.
+inputs:
+  tf_docs_working_dir:
+    description: Directories of terraform modules to generate docs for seperated by commas (conflicts with atlantis/find dirs)
+    required: false
+    default: '.'
+  tf_docs_atlantis_file:
+    description: Generate directories by parsing an atlantis formatted yaml to enable provide the file name to parse (eg atlantis.yaml) (disabled by default)
+    required: false
+    default: 'disabled'
+  tf_docs_find_dir:
+    description: Generate directories by running find ./tf_docs_find_dir -name *.tf (disabled by default)
+    required: false
+    default: 'disabled'
+  tf_docs_output_file:
+    description: File in module directory where the docs should be placed
+    required: false
+    default: 'USAGE.md'
+  tf_docs_content_type:
+    description: Generate document or table
+    required: false
+    default: 'table'
+  tf_docs_indention:
+    description: Indention level of Markdown sections [1, 2, 3, 4, 5] (default 2)
+    required: false
+    default: '2'
+  tf_docs_args:
+    description: Additional args to pass
+    required: false
+    default: '--sort-inputs-by-required'
+  tf_docs_output_method:
+    description: Method should be one of (replace/inject/print) where replace will replace the tf_docs_output_file, inject will inject the content between start and close delims and print will just print the output
+    required: false
+    default: 'inject'
+  tf_docs_git_push:
+    description: If true it will commit and push the changes
+    required: false
+    default: 'false'
+  tf_docs_git_commit_message:
+    description: Commit message
+    required: false
+    default: 'terraform-docs: automated action'
+  tf_docs_template:
+    description: When provided will be used as the template if/when the OUTPUT_FILE does not exist
+    default: |
+      # Usage
+      <!--- BEGIN_TF_DOCS --->
+      <!--- END_TF_DOCS --->
+    required: false
+
+outputs:
+  num_changed:
+    description: Number of files changed
+
+runs:
+  using: docker
+  image: Dockerfile
+
+branding:
+  icon: file-text
+  color: gray-dark

examples/test_b/README.md

@@ -0,0 +1,110 @@
+# Terraform GitHub Actions
+
+Terraform GitHub Actions allow you to execute Terraform commands within GitHub Actions.
+
+The output of the actions can be viewed from the Actions tab in the main repository view. If the actions are executed on a pull request event, a comment may be posted on the pull request.
+
+Terraform GitHub Actions are a single GitHub Action that executes different Terraform subcommands depending on the content of the GitHub Actions YAML file.
+
+## Success Criteria
+
+An exit code of `0` is considered a successful execution.
+
+## Usage
+
+The most common workflow is to run `terraform fmt`, `terraform init`, `terraform validate`, and `terraform plan` on all of the Terraform files in the root of the repository when a pull request is opened or updated. A comment will be posted to the pull request depending on the output of the Terraform subcommand being executed. This workflow can be configured by adding the following content to the GitHub Actions workflow YAML file.
+
+```yaml
+name: 'Terraform GitHub Actions'
+on:
+  - pull_request
+jobs:
+  terraform:
+    name: 'Terraform'
+    runs-on: ubuntu-latest
+    steps:
+      - name: 'Checkout'
+        uses: actions/checkout@master
+      - name: 'Terraform Format'
+        uses: hashicorp/terraform-github-actions@master
+        with:
+          tf_actions_version: 0.12.13
+          tf_actions_subcommand: 'fmt'
+          tf_actions_working_dir: '.'
+          tf_actions_comment: true
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      - name: 'Terraform Init'
+        uses: hashicorp/terraform-github-actions@master
+        with:
+          tf_actions_version: 0.12.13
+          tf_actions_subcommand: 'init'
+          tf_actions_working_dir: '.'
+          tf_actions_comment: true
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      - name: 'Terraform Validate'
+        uses: hashicorp/terraform-github-actions@master
+        with:
+          tf_actions_version: 0.12.13
+          tf_actions_subcommand: 'validate'
+          tf_actions_working_dir: '.'
+          tf_actions_comment: true
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      - name: 'Terraform Plan'
+        uses: hashicorp/terraform-github-actions@master
+        with:
+          tf_actions_version: 0.12.13
+          tf_actions_subcommand: 'plan'
+          tf_actions_working_dir: '.'
+          tf_actions_comment: true
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+```
+
+This was a simplified example showing the basic features of these Terraform GitHub Actions. Please refer to the examples within the `examples` directory for other common workflows.
+
+<!--- BEGIN_ACTION_DOCS --->
+## Inputs
+
+| Name | Description | Default | Required |
+|------|-------------|---------|----------|
+| tf\_actions\_cli\_credentials\_hostname | Hostname for the CLI credentials file. | app.terraform.io | false |
+| tf\_actions\_cli\_credentials\_token | Token for the CLI credentials file. | N/A | false |
+| tf\_actions\_comment | Whether or not to comment on pull requests. | true | false |
+| tf\_actions\_subcommand | Terraform subcommand to execute. | N/A | true |
+| tf\_actions\_version | Terraform version to install. | N/A | true |
+| tf\_actions\_working\_dir | Terraform working directory. | . | false |
+
+## Outputs
+
+| Name | Description |
+|------|-------------|
+| tf\_actions\_output | The Terraform outputs in JSON format. |
+| tf\_actions\_plan\_has\_changes | Whether or not the Terraform plan contained changes. |
+<!--- END_ACTION_DOCS --->
+
+## Secrets
+
+Secrets are similar to inputs except that they are encrypted and only used by GitHub Actions. It's a convenient way to keep sensitive data out of the GitHub Actions workflow YAML file.
+
+* `GITHUB_TOKEN` - (Optional) The GitHub API token used to post comments to pull requests. Not required if the `tf_actions_comment` input is set to `false`.
+
+Other secrets may be needed to authenticate with Terraform backends and providers.
+
+**WARNING:** These secrets could be exposed if the action is executed on a malicious Terraform file. To avoid this, it is recommended not to use these Terraform GitHub Actions on repositories where untrusted users can submit pull requests.
+
+## Environment Variables
+
+Environment variables are exported in the environment where the Terraform GitHub Actions are executed. This allows a user to modify the behavior of certain GitHub Actions.
+
+The usual [Terraform environment variables](https://www.terraform.io/docs/commands/environment-variables.html) are supported. Here are a few of the more commonly used environment variables.
+
+* [`TF_LOG`](https://www.terraform.io/docs/commands/environment-variables.html#tf_log)
+* [`TF_VAR_name`](https://www.terraform.io/docs/commands/environment-variables.html#tf_var_name)
+* [`TF_CLI_ARGS`](https://www.terraform.io/docs/commands/environment-variables.html#tf_cli_args-and-tf_cli_args_name)
+* [`TF_CLI_ARGS_name`](https://www.terraform.io/docs/commands/environment-variables.html#tf_cli_args-and-tf_cli_args_name)
+* `TF_WORKSPACE`
+
+Other environment variables may be configured to pass data into Terraform. If the data is sensitive, consider using [secrets](#secrets) instead.

examples/test_b/action.yml

@@ -0,0 +1,32 @@
+name: 'Terraform GitHub Actions'
+description: 'Runs Terraform commands via GitHub Actions.'
+author: 'HashiCorp, Inc. Terraform Team <[email protected]>'
+branding:
+  icon: 'terminal'
+  color: 'purple'
+inputs:
+  tf_actions_subcommand:
+    description: 'Terraform subcommand to execute.'
+    required: true
+  tf_actions_version:
+    description: 'Terraform version to install.'
+    required: true
+  tf_actions_cli_credentials_hostname:
+    description: 'Hostname for the CLI credentials file.'
+    default: 'app.terraform.io'
+  tf_actions_cli_credentials_token:
+    description: 'Token for the CLI credentials file.'
+  tf_actions_comment:
+    description: 'Whether or not to comment on pull requests.'
+    default: true
+  tf_actions_working_dir:
+    description: 'Terraform working directory.'
+    default: '.'
+outputs:
+  tf_actions_output:
+    description: 'The Terraform outputs in JSON format.'
+  tf_actions_plan_has_changes:
+    description: 'Whether or not the Terraform plan contained changes.'
+runs:
+  using: 'docker'
+  image: './Dockerfile'

src/README.tpl

@@ -0,0 +1,7 @@
+{{- $action := (datasource "action") -}}
+# {{ $action.name }}
+{{ $action.description }}
+
+# Configuration
+<!--- BEGIN_ACTION_DOCS --->
+<!--- END_ACTION_DOCS --->

src/default_template.tpl

@@ -0,0 +1,18 @@
+{{- define "escape_chars" }}{{ . | strings.ReplaceAll "_" "\\_" | strings.ReplaceAll "|" "\\|" | strings.ReplaceAll "*" "\\*" }}{{- end }}
+{{- define "sanatize_string" }}{{ . | strings.ReplaceAll "\n\n" "<br><br>" | strings.ReplaceAll "  \n" "<br>" | strings.ReplaceAll "\n" "<br>" | tmpl.Exec "escape_chars" }}{{- end }}
+{{- $action := (datasource "action") -}}
+## Inputs
+
+| Name | Description | Default | Required |
+|------|-------------|---------|----------|
+{{- range $key, $input := $action.inputs }}
+| {{ tmpl.Exec "escape_chars" $key }} | {{ if (has $input "description") }}{{ tmpl.Exec "sanatize_string" $input.description }}{{ else }}{{ tmpl.Exec "escape_chars" $key }}{{ end }} | {{ if (has $input "default") }}{{ tmpl.Exec "sanatize_string" $input.default }}{{ else }}N/A{{ end }} | {{ if (has $input "required") }}{{ $input.required }}{{ else }}false{{ end }} |
+{{- end }}
+
+## Outputs
+
+| Name | Description |
+|------|-------------|
+{{- range $key, $output := $action.outputs }}
+| {{ tmpl.Exec "escape_chars" $key }} | {{ if (has $output "description") }}{{ tmpl.Exec "sanatize_string" $output.description }}{{ else }}{{ tmpl.Exec "escape_chars" $key }}{{ end }} |
+{{- end }}