GitHub Actions Artifacts: Fix Missing Files and Dotfiles

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.

Separate hidden files from an empty match#

include-hidden-files and if-no-files-found control different boundaries. Use the staging listing to decide which one needs attention:

The upstream action metadata sets include-hidden-files to false and if-no-files-found to warn by default. Verify a required hidden entry before uploading without printing its contents:

1
- name: Verify required artifact entries
2
  shell: bash
3
  run: |
4
    set -euo pipefail
5
    test -f dist/.well-known/assetlinks.json
6
    find dist -type f -print | sort

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 upstream README currently uses @v7 in its examples, while its GHES note says upload-artifact@v4+ is not supported there and lists v3.2.2 or v3.2.2-node20 for GitHub Enterprise Server. Check the action repository when your runner or enterprise environment has a different support policy.

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#