{"id":19887962,"url":"https://github.com/terraform-docs/gh-actions","last_synced_at":"2025-04-09T05:12:25.199Z","repository":{"id":40559097,"uuid":"260824510","full_name":"terraform-docs/gh-actions","owner":"terraform-docs","description":"A Github action for generating Terraform module documentation using terraform-docs and gomplate","archived":false,"fork":false,"pushed_at":"2024-09-19T19:43:48.000Z","size":340,"stargazers_count":152,"open_issues_count":25,"forks_count":63,"subscribers_count":7,"default_branch":"main","last_synced_at":"2024-10-24T21:22:36.161Z","etag":null,"topics":["actions","github-actions","terraform","terraform-docs"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/terraform-docs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-05-03T03:58:25.000Z","updated_at":"2024-10-17T20:50:34.000Z","dependencies_parsed_at":"2024-11-12T18:05:53.705Z","dependency_job_id":"aa74c2b1-e33d-4330-9be2-df1cda42800d","html_url":"https://github.com/terraform-docs/gh-actions","commit_stats":{"total_commits":142,"total_committers":12,"mean_commits":"11.833333333333334","dds":0.5140845070422535,"last_synced_commit":"cfde42f79b15256c71f4b79ae1d6acea0f689952"},"previous_names":[],"tags_count":20,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/terraform-docs%2Fgh-actions","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/terraform-docs%2Fgh-actions/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/terraform-docs%2Fgh-actions/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/terraform-docs%2Fgh-actions/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/terraform-docs","download_url":"https://codeload.github.com/terraform-docs/gh-actions/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247980844,"owners_count":21027808,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["actions","github-actions","terraform","terraform-docs"],"created_at":"2024-11-12T18:05:32.557Z","updated_at":"2025-04-09T05:12:25.194Z","avatar_url":"https://github.com/terraform-docs.png","language":"Shell","funding_links":[],"categories":["Shell"],"sub_categories":[],"readme":"# terraform-docs GitHub Actions\n\nGenerate Terraform module documentation in pull requests.\n\nIn addition to statically defined directory modules, this module can search specific\nsubfolders or parse `atlantis.yaml` for module identification and doc generation. This\naction has the ability to auto commit docs to an open PR or after a push to a specific\nbranch.\n\n## Version\n\n`v1.4.1` (uses [terraform-docs] v0.20.0, which is supported and tested on Terraform\nversion 0.11+ and 0.12+ but may work for others.)\n\n### Upgrade v0 to v1\n\nRelease v1 contains following breaking changes:\n\n- default value of `output-file` has been changed to `README.md`\n- default value of `template` has been changed to\n\n  ```text\n  \u003c!-- BEGIN_TF_DOCS --\u003e\n  {{ .Content }}\n  \u003c!-- END_TF_DOCS --\u003e\n  ```\n\n## Usage\n\nTo use terraform-docs github action, configure a YAML workflow file, e.g.\n`.github/workflows/documentation.yml`, with the following:\n\n```yaml\nname: Generate terraform docs\non:\n  - pull_request\njobs:\n  docs:\n    runs-on: ubuntu-latest\n    steps:\n    - uses: actions/checkout@v3\n      with:\n        ref: ${{ github.event.pull_request.head.ref }}\n\n    - name: Render terraform docs inside the README.md and push changes back to PR branch\n      uses: terraform-docs/gh-actions@v1.4.1\n      with:\n        working-dir: .\n        output-file: README.md\n        output-method: inject\n        git-push: \"true\"\n```\n\n| NOTE: If `output-file` (default README.md) already exists it will need to be updated, with the block delimeters `\u003c!-- BEGIN_TF_DOCS --\u003e` and `\u003c!-- END_TF_DOCS --\u003e`, where the generated markdown will be injected. Otherwise the generated content will be appended at the end of the file. |\n| --- |\n\n| NOTE: If `output-file` (default README.md) doesn't exist it will created and the content will be saved into it. |\n| --- |\n\n## Configuration\n\n### Inputs\n\n| Name | Description | Default | Required |\n|------|-------------|---------|----------|\n| args | Additional arguments to pass to the command (see [full documentation](https://github.com/terraform-docs/terraform-docs/tree/master/docs)) | `\"\"` | false |\n| atlantis-file | Name of Atlantis file to extract list of directories by parsing it. To enable, provide the file name (e.g. `atlantis.yaml`) | `disabled` | false |\n| config-file | Name of terraform-docs config file. To enable, provide the file name (e.g. `.terraform-docs.yml`) | `disabled` | false |\n| fail-on-diff | Fail the job if there is any diff found between the generated output and existing file (ignored if `git-push` is set) | `false` | false |\n| find-dir | Name of root directory to extract list of directories by running `find ./find\\_dir -name \\*.tf` (ignored if `atlantis-file` is set) | `disabled` | false |\n| git-commit-message | Commit message | `terraform-docs: automated action` | false |\n| git-push | If true it will commit and push the changes | `false` | false |\n| git-push-sign-off | If true it will sign-off commit | `false` | false |\n| git-push-user-email | If empty the no-reply email of the GitHub Actions bot will be used (i.e. `github-actions[bot]@users.noreply.github.com`) | `\"\"` | false |\n| git-push-user-name | If empty the name of the GitHub Actions bot will be used (i.e. `github-actions[bot]`) | `\"\"` | false |\n| git-sub-dir | Subdirectory that terraform code is checked out into | `\"\"` | false |\n| indention | Indention level of Markdown sections [1, 2, 3, 4, 5] | `2` | false |\n| output-file | File in module directory where the docs should be placed | `README.md` | false |\n| output-format | terraform-docs format to generate content (see [all formats](https://github.com/terraform-docs/terraform-docs/blob/master/docs/FORMATS\\_GUIDE.md)) (ignored if `config-file` is set) | `markdown table` | false |\n| output-method | Method should be one of `replace`, `inject`, or `print`. Set as an empty string if `output.mode` and `output.file` are defined in config-file | `inject` | false |\n| recursive | If true it will update submodules recursively | `false` | false |\n| recursive-path | Submodules path to recursively update | `modules` | false |\n| template | When provided will be used as the template if/when the `output-file` does not exist. Set as an empty string if `output.template` is defined in config-file | `\u003c!-- BEGIN_TF_DOCS --\u003e\\n{{ .Content }}\\n\u003c!-- END_TF_DOCS --\u003e` | false |\n| working-dir | Comma separated list of directories to generate docs for (ignored if `atlantis-file` or `find-dir` is set) | `.` | false |\n\n#### Output Method (output-method)\n\n- `print`\n\n  This will just print the generated output\n\n- `replace`\n\n  This will create or replace the `output-file` at the determined module path(s)\n\n- `inject`\n\n  Instead of replacing the `output-file`, this will inject the generated documentation\n  into the existing file between the predefined delimeters: `\u003c!-- BEGIN_TF_DOCS --\u003e`\n  and `\u003c!-- END_TF_DOCS --\u003e`. If the file exists but does not contain the delimeters,\n  the action will append the generated content at the end of `output-file`. If the file\n  doesn't exist, it will create it using the value template which MUST have the delimeters.\n\n#### Auto commit changes\n\nTo enable you need to ensure a few things first:\n\n- set `git-push` to `true`\n- use `actions/checkout@v3` with the head ref for PRs or branch name for pushes\n  - PR\n\n    ```yaml\n    on:\n      - pull_request\n    jobs:\n      docs:\n        runs-on: ubuntu-latest\n        steps:\n        - uses: actions/checkout@v3\n          with:\n            ref: ${{ github.event.pull_request.head.ref }}\n    ```\n\n  - Push\n\n    ```yaml\n    on:\n      push:\n        branches:\n          - master\n    jobs:\n      docs:\n        runs-on: ubuntu-latest\n        steps:\n        - uses: actions/checkout@v3\n          with:\n            ref: master\n    ```\n\n### Outputs\n\n| Name | Description |\n|------|-------------|\n| num\\_changed | Number of files changed |\n\n## Examples\n\n### Single folder\n\n```yaml\n- name: Generate TF Docs\n  uses: terraform-docs/gh-actions@v1.4.1\n  with:\n    working-dir: .\n```\n\n### Multi folder\n\n```yaml\n- name: Generate TF Docs\n  uses: terraform-docs/gh-actions@v1.4.1\n  with:\n    working-dir: .,example1,example3/modules/test\n```\n\n### Use `atlantis.yaml` v3 to find all directories\n\n```yaml\n- name: Generate TF docs\n  uses: terraform-docs/gh-actions@v1.4.1\n  with:\n    atlantis-file: atlantis.yaml\n```\n\n### Find all `.tf` file under a given directory\n\n```yaml\n- name: Generate TF docs\n  uses: terraform-docs/gh-actions@v1.4.1\n  with:\n    find-dir: examples/\n```\n\n### Recursively under a given directory\n\n```yaml\n- name: Generate TF docs\n  uses: terraform-docs/gh-actions@v1.4.1\n  with:\n    working-dir: examples/\n    recursive: true\n    recursive-path: modules\n```\n\nComplete examples can be found [here](https://github.com/terraform-docs/gh-actions/tree/v1.4.1/examples).\n\n[terraform-docs]: https://github.com/terraform-docs/terraform-docs\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fterraform-docs%2Fgh-actions","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fterraform-docs%2Fgh-actions","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fterraform-docs%2Fgh-actions/lists"}