According to Github Action's official documentation (workflow events):
- The .github/workflows directory in your repository is searched for workflow files at the associated commit SHA or Git ref. The workflow files must be present in that commit SHA or Git ref to be considered. For example, if the event occurred on a particular repository branch, then the workflow files must be present in the repository on that branch.
Does than mean I have to make same changes to same workflow in both master/default branch and the particular repo branch ?
OR only update the workflow in the particular repo branch?
CodePudding user response:
The workflow being executed depends only on the workflow defined in that particular branch.
CodePudding user response:
This can be very confusing. To avoid confusion, we need to distinguish between what Git actually does (not that much), and what GitHub will do in various "events" (a lot of things).
GitHub define many events, many of which have nothing at all to do with Git. For instance, GitHub define events that occur when creating "issues" using the web interface or APIs. A GitHub issue isn't a Git commit at all: it's an entry (or sequence of entries) in a database that is invisible to Git.
Each GitHub event has a different set of definitions, and refers to:
- the "webhook event payload" and "activity types": these are GitHub-only entities
- the
GITHUB_SHA
: this refers to a hash ID (a Git OID ) in a Git repository, typically a commit hash ID; - The
GITHUB_REF
: this refers to a reference name in a Git repository, e.g., a branch name (but using the full spelling, i.e.,refs/heads/br
for branchbr
).
You must pore over that giant table of everything to see the complete list.
At the Git level (in any repository clone—yours or on GitHub)
At the Git level, branches don't matter, only commits matter. Either a commit has a file named .github/workflows/something
, or it doesn't. The commit is found by a commit hash ID, and that's what determines which commit we're looking at, and then that either has the file or doesn't. If it has the file, that commit has the file with the contents it had at the time you (or whoever) made that commit.
Note that every commit in Git stores a full snapshot of every file (that Git knew about at the time you, or whoever, made the commit). The files that Git knows about are the tracked files. A file is tracked if and only if it's in Git's index and therefore will be in the next commit. When you check out some commit (in order to do work and make a new commit), Git fills its index from the commit you checked out, so all the files that are in that commit are now tracked. You do your work, use git add
to update the index copies of files, use git add
and/or git rm
to add and/or remove files to/from Git's index (making them tracked or untracked), and then run git commit
to make a new commit. The snapshot you make now—in the new commit you make—has all (and exactly) those files that were in Git's index at the time you ran git commit
.
During a connection between Git and GitHub
When GitHub receive one or more new commits via git push
, GitHub will:
first, inspect those commits to make sure there are no overly large files in them, for instance;
then receive and inspect one or more branch and/or tag name requests as the last part of the
git push
operation:- the person or program doing the push may ask to set a branch name to a commit hash ID, creating or updating that branch name;
- or, the one doing the push may ask to delete a branch name.
Item 1 occurs for, e.g., git push origin mine:yours
, where I push commits as found in my (laptop) repository under the branch name mine
but request that your GitHub repository set its branch name yours
. Item 2 occurs for git push origin --delete yours
, where I've asked your GitHub repository to delete its branch name yours
.
In case of a git push
, GitHub will inspect and verify these final requests. If the push is allowed, and a workflow is to be triggered, GitHub will read the .github/workflows/*.yml
files1 in the commit hash ID that's part of the push request. That is, if I ran git push origin mine:yours
, the request may have looked like this:
- Here's a new commit with hash ID
a123456...
, here's it's snapshot, etc. - And now, if you will, please set your branch name
refs/heads/yours
toa123456...
.
Assuming I'm allowed to set this branch name in your repository, GitHub's workflow detection will look for .github/workflows/push
in commit a123456...
, because that's the commit hash ID I asked to set.
As an exception, if I asked to delete refs/heads/yours
(branch name yours
), GitHub will look for .github/workflows/*.yml
in the commit that is the tip of the default branch. The reason to do this is that deleting the name yours
means there's no longer any hash ID to use with this branch name: The branch name provides the hash ID, and the branch name is being removed.
Note that creating a new branch name with git push
should trigger both the create
event and the push
event, and deleting a branch name with git push
should trigger both the delete
and push
events as well. (The same goes for tag creation and deletion.)
1It's not clear what GitHub do with files in .github/workflows/
whose name does not end in .yml
, nor whether they allow names like .github/workflows/w1/foo.yml
. I have not attempted this myself to see what, if anything, happens with such files. The documentation shows only simple flat-namespace files ending with .yml
and that's all I've ever seen used.
Putting this all together again
The trick here is to remember that, at the Git level, Git really only cares about hash IDs. The hash ID of some commit lets Git find the files that go with that commit. This hash ID (or GITHUB_SHA
in the giant table) determines which files are in the commit.
GitHub extract the selected commit (well, inspect it anyway) and look for the .github/workflows/*.yml
files in that commit. For each such file, they (GitHub) read it and execute the rules found therein, according to the event that triggered this reading-and-executing.
Since only push events can create new commits,2 the only time you need to worry about this GITHUB_SHA
being a new and different commit than the one you'd have had selected by some previous GITHUB_SHA
is for git push
events. And, since a typical git push
looks more like git push origin somebranch
, the fact that the name in my laptop repository could differ from the name in your GitHub repository isn't particularly tricky. If I use a different name in my repository, it's up to me, the guy doing the tricky thing, to know to use the right on: push: branches: ...
things if I'm doing that.
2Well, push events, or any file creation done through the web interface. I assume the latter shows up as a sort of faked-up push event, which is pretty straightforward to do and might even be how it's implemented internally in the first place.