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.

Let's say you want to do something when there is a push in your GitHub repository, almost always, when there is a push to the default branch of your repository. Let's first understand github.events. Let's say you have the following GitHub Actions workflow.

name: my-workflow
run-name: ${{ github.workflow }} run by ${{ github.actor }}
on:
  push
jobs:
  my-job:
    runs-on: ubuntu-latest
    steps:
      - run: echo '${{ toJSON(github.event) }}'    

Or like this, to only trigger the action when there is a push to the main branch of the repository.

name: my-workflow
run-name: ${{ github.workflow }} run by ${{ github.actor }}
on:
  push:
    branches: ['main']
jobs:
  my-job:
    runs-on: ubuntu-latest
    steps:
      - run: echo '${{ toJSON(github.event) }}'    

When there is a push in your repository, the GitHub Action will be triggered and the action should have JSON that looks something like this.

{
  "after": "9eba1322c77d8f64322485f46ce6705ca7a1cca3",
  "base_ref": null,
  "before": "a0d5561beb1f750b21f5ce8466f2cc873cdaceaa",
  "commits": [
    {
      "author": {
        "email": "john.doe@example.com",
        "name": "John Doe",
        "username": "John-Doe_example"
      },
      "committer": {
        "email": "john.doe@example.com",
        "name": "John Doe",
        "username": "John-Doe_example"
      },
      "distinct": true,
      "id": "ba1b72d0790e66d1225497e1307fe4a429f55454",
      "message": "my commit",
      "timestamp": "2025-07-30T02:08:04-05:00",
      "tree_id": "1c5c24051f4a419d512366193dd44e4695fd86dc",
      "url": "https://github.com/my-org/my-repo/commit/ba1b72d0790e66d1225497e1307fe4a429f55454"
    },
  ],
  "compare": "https://github.com/my-org/my-repo/compare/a0d5561beb1f...9eba1322c77d",
  "created": false,
  "deleted": false,
  "enterprise": {
    "avatar_url": "https://avatars.githubusercontent.com/b/22369?v=4",
    "created_at": "2023-02-17T08:51:26Z",
    "description": null,
    "html_url": "https://github.com/enterprises/my-org",
    "id": 22369,
    "name": "Acme",
    "node_id": "E_kgDNV2E",
    "slug": "Acme",
    "updated_at": "2025-05-09T15:27:57Z",
    "website_url": null
  },
  "forced": false,
  "head_commit": {
    "author": {
      "email": "john.doe@example.com",
      "name": "John Doe",
      "username": "John-Doe_example"
    },
    "committer": {
      "email": "noreply@github.com",
      "name": "GitHub",
      "username": "web-flow"
    },
    "distinct": true,
    "id": "9eba1322c77d8f64322485f46ce6705ca7a1cca3",
    "message": "Merge pull request #140 from my-org/poc\n\nb",
    "timestamp": "2025-07-30T02:08:45-05:00",
    "tree_id": "1c5c24051f4a419d512366193dd44e4695fd86dc",
    "url": "https://github.com/my-org/my-repo/commit/9eba1322c77d8f64322485f46ce6705ca7a1cca3"
  },
  "organization": {
    "avatar_url": "https://avatars.githubusercontent.com/u/127796631?v=4",
    "description": "The main Acme organization.",
    "events_url": "https://api.github.com/orgs/my-org/events",
    "hooks_url": "https://api.github.com/orgs/my-org/hooks",
    "id": 127796631,
    "issues_url": "https://api.github.com/orgs/my-org/issues",
    "login": "acme",
    "members_url": "https://api.github.com/orgs/my-org/members{/member}",
    "node_id": "O_kgDOB54Flw",
    "public_members_url": "https://api.github.com/orgs/my-org/public_members{/member}",
    "repos_url": "https://api.github.com/orgs/my-org/repos",
    "url": "https://api.github.com/orgs/my-org"
  },
  "pusher": {
    "email": "john.doe@example.com",
    "name": "John Doe",
  },
  "ref": "refs/heads/main",
  "repository": {
    "allow_forking": true,
    "archive_url": "https://api.github.com/repos/my-org/my-repo/{archive_format}{/ref}",
    "archived": false,
    "assignees_url": "https://api.github.com/repos/my-org/my-repo/assignees{/user}",
    "blobs_url": "https://api.github.com/repos/my-org/my-repo/git/blobs{/sha}",
    "branches_url": "https://api.github.com/repos/my-org/my-repo/branches{/branch}",
    "clone_url": "https://github.com/my-org/my-repo.git",
    "collaborators_url": "https://api.github.com/repos/my-org/my-repo/collaborators{/collaborator}",
    "comments_url": "https://api.github.com/repos/my-org/my-repo/comments{/number}",
    "commits_url": "https://api.github.com/repos/my-org/my-repo/commits{/sha}",
    "compare_url": "https://api.github.com/repos/my-org/my-repo/compare/{base}...{head}",
    "contents_url": "https://api.github.com/repos/my-org/my-repo/contents/{+path}",
    "contributors_url": "https://api.github.com/repos/my-org/my-repo/contributors",
    "created_at": 1737459780,
    "custom_properties": {},
    "default_branch": "main",
    "deployments_url": "https://api.github.com/repos/my-org/my-org/deployments",
    "description": "my repo",
    "disabled": false,
    "downloads_url": "https://api.github.com/repos/my-org/my-repo/downloads",
    "events_url": "https://api.github.com/repos/my-org/my-repo/events",
    "fork": false,
    "forks": 0,
    "forks_count": 0,
    "forks_url": "https://api.github.com/repos/my-org/my-repo/forks",
    "full_name": "my-org/my-repo",
    "git_commits_url": "https://api.github.com/repos/my-org/my-repo/git/commits{/sha}",
    "git_refs_url": "https://api.github.com/repos/my-org/my-repo/git/refs{/sha}",
    "git_tags_url": "https://api.github.com/repos/my-org/my-repo/git/tags{/sha}",
    "git_url": "git://github.com/my-org/my-repo.git",
    "has_discussions": false,
    "has_downloads": true,
    "has_issues": true,
    "has_pages": false,
    "has_projects": true,
    "has_wiki": true,
    "homepage": null,
    "hooks_url": "https://api.github.com/repos/my-org/my-repo/hooks",
    "html_url": "https://github.com/my-org/my-repo",
    "id": 919998835,
    "is_template": false,
    "issue_comment_url": "https://api.github.com/repos/my-org/my-repo/issues/comments{/number}",
    "issue_events_url": "https://api.github.com/repos/my-org/my-repo/issues/events{/number}",
    "issues_url": "https://api.github.com/repos/my-org/my-repo/issues{/number}",
    "keys_url": "https://api.github.com/repos/my-org/my-repo/keys{/key_id}",
    "labels_url": "https://api.github.com/repos/my-org/my-repo/labels{/name}",
    "language": "Python",
    "languages_url": "https://api.github.com/repos/my-org/my-repo/languages",
    "license": null,
    "master_branch": "main",
    "merges_url": "https://api.github.com/repos/my-org/my-repo/merges",
    "milestones_url": "https://api.github.com/repos/my-org/my-repo/milestones{/number}",
    "mirror_url": null,
    "name": "my-repo",
    "node_id": "R_kgDONtYRcw",
    "notifications_url": "https://api.github.com/repos/my-org/my-repo/notifications{?since,all,participating}",
    "open_issues": 2,
    "open_issues_count": 2,
    "organization": "acme",
    "owner": {
      "avatar_url": "https://avatars.githubusercontent.com/u/127796631?v=4",
      "email": null,
      "events_url": "https://api.github.com/users/my-org/events{/privacy}",
      "followers_url": "https://api.github.com/users/my-org/followers",
      "following_url": "https://api.github.com/users/my-org/following{/other_user}",
      "gists_url": "https://api.github.com/users/my-org/gists{/gist_id}",
      "gravatar_id": "",
      "html_url": "https://github.com/my-org",
      "id": 127796631,
      "login": "my-org",
      "name": "my-org",
      "node_id": "O_kgDOB54Flw",
      "organizations_url": "https://api.github.com/users/my-org/orgs",
      "received_events_url": "https://api.github.com/users/my-org/received_events",
      "repos_url": "https://api.github.com/users/my-org/repos",
      "site_admin": false,
      "starred_url": "https://api.github.com/users/my-org/starred{/owner}{/repo}",
      "subscriptions_url": "https://api.github.com/users/my-org/subscriptions",
      "type": "Organization",
      "url": "https://api.github.com/users/my-org",
      "user_view_type": "public"
    },
    "private": true,
    "pulls_url": "https://api.github.com/repos/my-org/my-org/pulls{/number}",
    "pushed_at": 1753859325,
    "releases_url": "https://api.github.com/repos/my-org/my-org/releases{/id}",
    "size": 690,
    "ssh_url": "git@github.com:my-org/my-org.git",
    "stargazers": 0,
    "stargazers_count": 0,
    "stargazers_url": "https://api.github.com/repos/my-org/my-org/stargazers",
    "statuses_url": "https://api.github.com/repos/my-org/my-org/statuses/{sha}",
    "subscribers_url": "https://api.github.com/repos/my-org/my-org/subscribers",
    "subscription_url": "https://api.github.com/repos/my-org/my-org/subscription",
    "svn_url": "https://github.com/my-org/my-org",
    "tags_url": "https://api.github.com/repos/my-org/my-org/tags",
    "teams_url": "https://api.github.com/repos/my-org/my-org/teams",
    "topics": [
      "shipwright"
    ],
    "trees_url": "https://api.github.com/repos/my-org/my-org/git/trees{/sha}",
    "updated_at": "2025-07-30T07:07:13Z",
    "url": "https://api.github.com/repos/my-org/my-org",
    "visibility": "internal",
    "watchers": 0,
    "watchers_count": 0,
    "web_commit_signoff_required": false
  },
  "sender": {
    "avatar_url": "https://avatars.githubusercontent.com/u/127442491?v=4",
    "events_url": "https://api.github.com/users/John-Doe_acme/events{/privacy}",
    "followers_url": "https://api.github.com/users/John-Doe_acme/followers",
    "following_url": "https://api.github.com/users/John-Doe_acme/following{/other_user}",
    "gists_url": "https://api.github.com/users/John-Doe_acme/gists{/gist_id}",
    "gravatar_id": "",
    "html_url": "https://github.com/John-Doe_acme",
    "id": 127442491,
    "login": "John-Doe_acme",
    "node_id": "U_kgDOB5ieOw",
    "organizations_url": "https://api.github.com/users/John-Doe_acme/orgs",
    "received_events_url": "https://api.github.com/users/John-Doe_acme/received_events",
    "repos_url": "https://api.github.com/users/John-Doe_acme/repos",
    "site_admin": false,
    "starred_url": "https://api.github.com/users/John-Doe_acme/starred{/owner}{/repo}",
    "subscriptions_url": "https://api.github.com/users/John-Doe_acme/subscriptions",
    "type": "User",
    "url": "https://api.github.com/users/John-Doe_acme",
    "user_view_type": "public"
  }
}

Almost always, you are just interested in the commits that were included in the push. 

name: my-workflow
run-name: ${{ github.workflow }} run by ${{ github.actor }}
on:
  push
jobs:
  my-job:
    runs-on: ubuntu-latest
    steps:
      - run: echo '${{ toJSON(github.event.commits) }}'

Which should now return just the commits that were pushed. In this example, there are two commits being pushed.

{
  "author": {
    "email": "john.doe@example.com",
    "name": "John Doe",
    "username": "John-Doe_example"
  },
  "committer": {
    "email": "john.doe@example.com",
    "name": "John Doe",
    "username": "John-Doe_example"
  },
  "distinct": true,
  "id": "ba1b72d0790e66d1225497e1307fe4a429f55454",
  "message": "foo commit",
  "timestamp": "2025-07-30T02:08:04-05:00",
  "tree_id": "1c5c24051f4a419d512366193dd44e4695fd86dc",
  "url": "https://github.com/my-org/my-repo/commit/ba1b72d0790e66d1225497e1307fe4a429f55454"
},
{
  "author": {
    "email": "john.doe@example.com",
    "name": "John Doe",
    "username": "John-Doe_example"
  },
  "committer": {
    "email": "john.doe@example.com",
    "name": "John Doe",
    "username": "John-Doe_example"
  },
  "distinct": true,
  "id": "4071d84ac304c5203bc9a1fbfd5244911c06d8d3",
  "message": "bar commit",
  "timestamp": "2025-07-30T02:08:04-05:00",
  "tree_id": "1c5c24051f4a419d512366193dd44e4695fd86dc",
  "url": "https://github.com/my-org/my-repo/commit/4071d84ac304c5203bc9a1fbfd5244911c06d8d3"
}

Notice the above output does not list the files associated with each commit. The REST API can be used to return the files associated with each commit.

name: my-workflow
run-name: ${{ github.workflow }} run by ${{ github.actor }}
on:
  push
jobs:
  my-job:
    runs-on: ubuntu-latest
    steps:
      - run: for commit in ${{ join(github.event.commits.*.id, ' ') }}; do echo commit $commit => `gh api repos/${{ github.event.repository.organization }}/${{ github.event.repository.name }}/commits/$commit | jq .files[].filename`; done;

Which should return something like this.

commit ba1b72d0790e66d1225497e1307fe4a429f55454 => path/to/foo.txt commit 4071d84ac304c5203bc9a1fbfd5244911c06d8d3 => path/to/bar.txt

It is important to recognize that when a pull request is merged into the default branch of the repository, there will be two or more commits for the same file, where one or more commits will be for the commits made to the file in the pull request and a commit for when the pull request was merged into the default branch of the repository. It is noteworthy that the commits made in the pull request will have distinct: false and the commit for when the pull request was merged will have distinct: true thus distinct can be used to distinguish the commits in the pull request from the merge.

{
  "author": {
    "email": "john.doe@example.com",
    "name": "John Doe",
    "username": "John-Doe_example"
  },
  "committer": {
    "email": "john.doe@example.com",
    "name": "John Doe",
    "username": "John-Doe_example"
  },
  "distinct": false,
  "id": "ba1b72d0790e66d1225497e1307fe4a429f55454",
  "message": "foo commit",
  "timestamp": "2025-07-30T02:08:04-05:00",
  "tree_id": "1c5c24051f4a419d512366193dd44e4695fd86dc",
  "url": "https://github.com/my-org/my-repo/commit/ba1b72d0790e66d1225497e1307fe4a429f55454"
},
{
  "author": {
    "email": "john.doe@example.com",
    "name": "John Doe",
    "username": "John-Doe_example"
  },
  "committer": {
    "email": "john.doe@example.com",
    "name": "John Doe",
    "username": "John-Doe_example"
  },
  "distinct": true,
  "id": "4071d84ac304c5203bc9a1fbfd5244911c06d8d3",
  "message": "Merge pull request #123 from my-org/my-branch\n\nmy-branch",
  "timestamp": "2025-07-30T02:08:04-05:00",
  "tree_id": "1c5c24051f4a419d512366193dd44e4695fd86dc",
  "url": "https://github.com/my-org/my-repo/commit/4071d84ac304c5203bc9a1fbfd5244911c06d8d3"
}