GitHub Actions Artifacts Missing Dotfiles? Use include-hidden-files Safely

Confirm what exists before uploading#

First inspect the directory that the workflow intends to publish. This checks the filesystem without printing file contents:

1
- name: Inspect artifact staging
2
  shell: bash
3
  run: |
4
    set -euo pipefail
5
    test -d dist
6
    find dist -print | sort

If the expected path is absent here, the problem is in the build or staging step, not the artifact action. If the path exists and begins with ., the default hidden-file filter is the likely cause.

Remember that “hidden” here means a dot-prefixed file or directory. A file marked hidden by an operating-system attribute but named report.json is not the same case. The action’s official README documents this behavior and the opt-in input.

Upload a narrow directory with an explicit exclusion#

For a build that needs a hidden .well-known directory, upload only the build output and exclude environment files:

1
- name: Upload website artifact
2
  uses: actions/upload-artifact@v7
3
  with:
4
    name: website
5
    path: |
6
      dist/
7
      !dist/.env
8
      !dist/**/.env
9
    include-hidden-files: true
10
    if-no-files-found: error

The negative patterns are a second line of defense, not a replacement for staging hygiene. Add exclusions for the secret formats your build can generate, then review the final path list in CI logs. If your artifact needs only one hidden path, an even narrower staging directory is easier to audit than enabling hidden-file upload across all of dist.

if-no-files-found: error changes a missing output from a warning into a failed job. That is usually the right choice for release bundles, deployment packages, and test reports: a green workflow should not silently publish an empty or incomplete artifact.

Stage only the files that belong in the artifact#

When a tool writes hidden state beside the desired output, copy the intended files to a clean directory before uploading:

1
- name: Prepare release bundle
2
  shell: bash
3
  run: |
4
    set -euo pipefail
5
    rm -rf artifact-staging
6
    mkdir -p artifact-staging/.well-known
7
    cp -R dist/assets artifact-staging/assets
8
    cp dist/.well-known/assetlinks.json artifact-staging/.well-known/
9

10
- name: Upload release bundle
11
  uses: actions/upload-artifact@v7
12
  with:
13
    name: release-bundle
14
    path: artifact-staging/
15
    include-hidden-files: true
16
    if-no-files-found: error

The staging pattern makes the upload contract visible in the workflow. It also limits the blast radius if a future build tool starts creating a new dotfile under dist.

Do not print secret values while debugging. find is useful for names and paths, but a recursive cat, an environment dump, or an unfiltered archive listing can expose credentials in public workflow logs. Review the action permissions and retention policy as part of the artifact design.

Check the action and repository boundary#

Use the major version supported by your repository. The current upload-artifact documentation shows @v7; check the action repository when your runner or GitHub Enterprise environment has a different support policy. GitHub Enterprise Server support and artifact version compatibility can differ from GitHub.com.

Artifacts are for files produced by a workflow, not for passing an arbitrary working tree between jobs. Give each job a clear output directory and a unique artifact name. When a later job consumes the bundle, validate the expected hidden path after download instead of assuming that a successful upload means every file was present.

For a related workflow input issue, see the guide to boolean workflow_dispatch inputs. The same principle applies here: verify the value at the boundary where GitHub interprets it, rather than trusting a superficially successful run.

FAQ#