Required checks do not run on terraform-docs commits, blocking auto-merge

[rpdelaney]

What problem are you facing?

When using terraform-docs with push enabled, the commit pushed by terraform-docs does not have required checks run on it. Therefore, automation for updating dependencies cannot self-merge if checks are required by branch protection rules.

How could terraform-docs help solve your problem?

#79 suggested force-pushing the terraform-docs commit. I don't want terraform-docs to co-mingle its commits with mine.

Instead, it may be better to delay the workflows until tf-docs has pushed, or else restart the workflows after pushing.

[jonathanio]

This is a limitation of the GITHUB_TOKEN and not the GitHub Action. If you use the default GITHUB_TOKEN provided in the Workflow for the repository, then that token is restricted from running GitHub Workflows on push to prevent recursive triggering.

I have spoken about this with GitHub (i.e. prevent the automatically generated GITHUB_TOKEN from pushing if that token was triggered through another generated GITHUB_TOKEN, rather than prevent the automatically generated GITHUB_TOKEN from running Workflows) but it's unlikely to be dealt with I think any time soon.

You either will need to manually run the Workflows after the commit has been made (or automate that process, which is what I've done), or create a Personal Access Token that is used in place of the automatically generated GITHUB_TOKEN, which will allow the triggering of the Workflows on pushes.

[rpdelaney]

Hi @jonathanio ! Thank you for this response. Do you happen to have an example handy of how you automate running the workflows after the terraform-docs commit is pushed? Managing personal access tokens would likely make this more effort than it's worth for us, unfortunately.

[jonathanio]

I'm in the process of rebuilding a lot of my infrastructure, so it's a bit all over the place, but if you take a look at my workflows for one of my older Terraform modules, you can see I've built up a tiered set of workflows. One will trigger on Pull Requests (i.e. pushes and opens), the other on labels being added. They then each call the CI as a reusable workflow internally.

This is needed to ensure that the CI Workflows are always at the same level, and therefore the required status checks can match regardless of how it was called. If terraform-ci.yaml is called by a Pull Request, but terraform-trigger-label.yaml runs and then calls terraform-ci.yaml via workflow_call, you get "Terraform CI / ..." and "Label / Terraform CI / ..." respectively, which breaks the status checks (learnt the hard way 😄)

I'm using Mergify now too to help automate when the labels get added, reviews approved, etc. (see my mergify.yml configuration. So far it's working well.

Like you, I didn't like the idea of PATs in this context as limiting their scope to the repository is difficult unless you go down the GitHub App route, which provides other risks.

[rpdelaney]

That first link looks like a private repo, but I'll check out the other one. Thanks again.

[jonathanio]

Oops! You're right. I've updated the link above to a gist which has the files and layout. Hopefully that'll help.

[jmreicha]

or create a Personal Access Token that is used in place of the automatically generated GITHUB_TOKEN, which will allow the triggering of the Workflows on pushes.

Do you have an example of this somewhere? I'm trying with the following but it isn't working:

      ...
      - name: Render terraform docs inside the README.md and push changes back to PR branch
        uses: terraform-docs/gh-actions@f6d59f89a280fa0a3febf55ef68f146784b20ba0 # v1.0.0
        env:
          GITHUB_TOKEN: ${{ secrets.MY_TOKEN }}
        with:
          args: --hide-empty=true
          git-push: "true"
          recursive: true
          recursive-path: .
          working-dir: modules/

[jonathanio]

Do you have an example of this somewhere? I'm trying with the following but it isn't working:

terraform-docs does not use the GITHUB_TOKEN directly, as the action creates the change via the utility and then runs git add, git commit, and git push directly against the locally checked-out repository. It's the git push where the GITHUB_TOKEN is required, as that's when/where the authentication is processed.

As such, you need to update your checkout action:

      - name: Checkout the repository
        uses: actions/checkout@v4
        with:
          token: ${{ secrets.MY_TOKEN || secrets.GITHUB_TOKEN }}

Update that job, and your push back to the repository should now be under the required principal.

[jmreicha]

Ah yep, that did the trick. Thank you for the help and quick response!