GitHub Actions can be used to do something whenever something happens in one of your GitHub repositories. If you are not familiar with GitHub Actions, check out my article Getting Started with GitHub Actions.

For example, let's say you have a repository named my-repo that contains 2 files, foo.jpg and bar.jpg, perhaps like this.

• https://github.com/JohnDoe/my-repo/blob/main/images/foo.jpg
• https://github.com/JohnDoe/my-repo/blob/main/images/bar.jpg

Here is an example of how to list the file in the main branch of the same repository as the GitHub Action when a commit is pushed to the main branch of the repository.

name: my-github-action-workflow
run-name: ${{ github.workflow }} run by ${{ github.actor }}
on:
  push:
    branches:
      - main
jobs:
  my-job:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout the main branch of this repository
        uses: actions/checkout@v4

      - name: List files in the repository
        run: ls ${{ github.workspace }}

Here is an example of how to list the file in the main branch of a different repository as the GitHub Action when a commit is pushed to the main branch of the repository the GitHub Action is in. In this example, the files in the main branch of the github.com/org/repo_name.git repo will be listed.

name: my-github-action-workflow
run-name: ${{ github.workflow }} run by ${{ github.actor }}
on:
  push:
    branches:
      - main
jobs:
  my-job:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout the main branch of repo org/repo_name
        uses: actions/checkout@v4
        with:
          repository: 'org/repo_name'
          token: ${{ secrets.token }}        

      - name: List files in the repository
        run: ls ${{ github.workspace }}

And here is an example of how to the list all of the files in a branch of a pull request.

name: my-github-action-workflow
run-name: ${{ github.workflow }} run by ${{ github.actor }}
on:
  pull_request:
    types: [opened]
jobs:
  my-job:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout pull request ${{ github.event.pull_request.head.ref }}
        uses: actions/checkout@v4
        with:
          fetch-depth: 0
          ref: ${{ github.event.pull_request.head.ref }}
          repository: ${{ github.event.pull_request.head.repo.full_name }}

      - name: List all of the files in the branch
        run: ls ${{ github.workspace }}

And here is example of how to list all changed files using tj-actions/changed-files

name: my-github-action-workflow
run-name: ${{ github.workflow }} run by ${{ github.actor }}
on:
  push:
    branches:
      - main
jobs:
  my-job:
    runs-on: ubuntu-latest
    steps:      
      - name: Checkout the main branch
        uses: actions/checkout@v4

      - name: Get changed files
        id: changed-files
        uses: tj-actions/changed-files@v40

      - name: List all changed files
        run: |
          for file in ${{ steps.changed-files.outputs.all_changed_files }}; do
            echo "$file was changed"
          done

And here is an example of how to list all of the files in a branch of a pull request that were changed.

name: my-github-action-workflow
run-name: ${{ github.workflow }} run by ${{ github.actor }}
on:
  push:
    branches:
      - main
jobs:
  my-job:
    runs-on: ubuntu-latest
    steps:      
      - name: Checkout pull request ${{ github.event.pull_request.head.ref }}
        uses: actions/checkout@v4
        with:
          ref: ${{ github.event.pull_request.head.ref }}
          repository: ${{ github.event.pull_request.head.repo.full_name }}

      - name: Get the list of diff files in the pull request branch ${{ github.event.pull_request.head.ref }}
        id: diff
        run: echo "files=$(git diff --name-only -r HEAD^1 HEAD | xargs)" >> $GITHUB_OUTPUT

      - name: List all diff files
        run: echo '${{ steps.diff.outputs.files }}'

Or like this, using tj-actions/changed-files.

name: my-github-action-workflow
run-name: ${{ github.workflow }} run by ${{ github.actor }}
on:
  push:
    branches:
      - main
jobs:
  my-job:
    runs-on: ubuntu-latest
    steps:      
      - name: Checkout pull request ${{ github.event.pull_request.head.ref }}
        uses: actions/checkout@v4
        with:
          ref: ${{ github.event.pull_request.head.ref }}
          repository: ${{ github.event.pull_request.head.repo.full_name }}

      - name: Get the list of changed files in pull request ${{ github.event.pull_request.head.ref }}
        id: changed-files
        uses: tj-actions/changed-files@v40

      - name: List all changed files in pull request ${{ github.event.pull_request.head.ref }}
        run: echo '${{ steps.changed-files.outputs.all_changed_files }}'

Often, there will be certain files you'll want to ignore, such as README.md and files in the .github/workflows directory. Files can be ignored by including files_ignore.

jobs:  
  my-job:
    runs-on: ubuntu-latest
    steps:
      - name: Checking out the repository code
        uses: actions/checkout@v4

      - name: Get changed files excluding README.md and files in the .github/workflows directory
        id: changed-files
        uses: tj-actions/changed-files@v40
        with:
          separator: ","   
          files_ignore: |
            README.md
            .github/workflows/*

      - name: changed files
        run: echo "changed files = ${{ steps.changed-files.outputs.all_changed_files }}"

      - name: changed files count
        run: echo "changed files count = ${{ steps.changed-files.outputs.all_changed_files_count }}"

    outputs:
      changed_files_count: ${{ steps.changed-files.outputs.all_changed_files_count }}

Which should return something like this.

If you are including path in actions/checkout so that the repository is checked out to a certain directory in the runner VM then you'll want to also use the same path in tj-actions/changed-files.

name: GitHub Action
run-name: ${{ github.workflow }} run by ${{ github.actor }}
on:
  push:
    branches:
      - main
jobs:
  github-action-job:
    runs-on: ubuntu-latest
    steps:      
      - name: Checking out the repository code . . .
        uses: actions/checkout@v4
        with:
          path: 'my_directory'

      - name: Get changed files
        id: changed-files
        uses: tj-actions/changed-files@v40
        with:
          path: 'my_directory'

      - name: List all changed files
        run: echo '${{ steps.changed-files.outputs.all_changed_files }}'

And here is how to get the changed files as JSON.

name: GitHub Action
run-name: ${{ github.workflow }} run by ${{ github.actor }}
on:
  push:
    branches:
      - main
jobs:
  github-action-job:
    runs-on: ubuntu-latest
    steps:      
      - name: Checking out the repository code . . .
        uses: actions/checkout@v4

      - name: Get changed files
        id: changed-files
        uses: tj-actions/changed-files@v40
        with:
          json: true
          escape_json: true

      - name: List all changed files as escaped JSON
        run: echo '${{ steps.changed-files.outputs.all_changed_files }}'

Which should output something like this.

echo 'files = ["path/to/foo.txt"]["path/to/bar.txt"]