Document .gitignore behaviour

[corollari]

Description

Currently, all files that are set to be ignored in .gitignore will not be deployed by the action. This seems to be caused by the git clone operation and, while I haven't been able to find any discussion on this in issues or PRs (I used github's search tool, so I might be on the wrong here), I think it's safe to assume that this is the intended behaviour.

I believe that this behaviour could be counterintuitive to some users, so it may be interesting to document it on the readme, or at least discuss the idea here.

Reproduction

1. Create a repository that includes a .gitignore file that blacklists some files
2. Set up a CI pipeline that deploys the directory that contains the .gitignore file using this action
3. Files specified on .gitignore will not be deployed

You can see this behaviour on this CI run.

Reasons why this can be unexpected

I personally got confused by this behaviour, as I expected .gitignored files to be deployed. My thought process went along the lines of:

1. People usually deploy build artifacts
2. Build artifacts are usually excluded from git through .gitignore
3. Thus, .gitignore files are probably not ignored when deploying

[corollari]

This is not a bug, sorry for botching the label.

[peaceiris]

When your publish_dir contains some .gitignore files, this action just follows the definitions. Since the deployment assets will be under Git control with the GitHub Pages spec, this is a basic Git behavior.

In the first place, .gitignore file is unnecessary as deployment assets. It is desired your publish_dir has no .gitignore files. I do not know any Static Site Generator that outputs a .gitignore file as build assets.

In your case, your publish_dir targets a Git repository and includes some .gitignore files. We can remove .gitignore files before this action as follows.

- run: find ./out -name ".gitignore" -delete

- name: Deploy
  uses: peaceiris/actions-gh-pages@v3
  with:
    github_token: ${{ secrets.GITHUB_TOKEN }}
    publish_dir: ./out

Or, the following setting will also satisfy your demand.

- name: Deploy
  uses: peaceiris/[email protected]
  with:
    github_token: ${{ secrets.GITHUB_TOKEN }}
    publish_dir: ./out
    exclude_assets: '.github,**/.gitignore'

I believe that this behaviour could be counterintuitive to some users, so it may be interesting to document it on the readme, or at least discuss the idea here.

Thanks to your posting, Someone who is interesting in this can find this issue in the future.

[corollari]

Yep, so this behaviour is fine but what are your thoughts on documenting this on the readme? Do you believe that it's best to keep it on this issue only?

[peaceiris]

what are your thoughts on documenting this on the readme?

Thank you for suggesting this.

First of all, I strongly recommend users who are facing this case to reconsider a project structure or CI/CD workflow not to set a Git repository to the publish_dir.

And, I do not know what to describe this since this case looks natural behavior for me. In my opinion, I don't think documenting is important.

If you have a kindly explanation about this, I am willing to merge your suggestion. :-)

[corollari]

Personally, I am setting up a repository that hosts different projects, and each one of these will have it's own CI workflow, which publishes the build artifacts to a different subdirectory on gh-pages. I was planning on doing that using keep_file on the whole repo (in a manner very similar to what you described in #324), so, at the end of the day, I will be publishing a git repository on publish_dir.

Now, it's possible to change the CI to isolate the published subdirectories from the rest of the github repo, but that didn't seem as something that needed to be done, so I just went ahead with that and got bit by having all of my build artifacts (which are on .gitignores) not be deployed.

With that said, I seem to be the only one that has run into this problem thus far, so I believe it's fine to not document it, just thought that I would explain my case since other users might run into the same problem.

[ChildishGiant]

An option to use a custom gitignore would really help this feel less hacky

[peaceiris]

@ChildishGiant We can implement it with simple coreutils commands as follows. As I mentioned above, find -delete can remove extra assets from the publishing directory before deployment.

- run: cp ./.gitignore.production ./public/.gitignore

- name: Deploy
  uses: peaceiris/actions-gh-pages@v3
  with:
    github_token: ${{ secrets.GITHUB_TOKEN }}
    publish_dir: ./public

[github-actions]

This issue has been LOCKED because of it being resolved!

The issue has been fixed and is therefore considered resolved.
If you still encounter this or it has changed, open a new issue instead of responding to solved ones.

Log | Bot Usage