v1 Release - Cleanup, Tests, & Added Options (#16)

.github/workflows/test.yml

@@ -0,0 +1,122 @@
+name: Submodule Action Unit Tests
+on: [push, pull_request]
+
+# To test this action we rely on an external repo with commits that have all the scenarios. 
+# That repo is: https://github.com/jtmullen/submodule-action-test-parent
+# These tests do not cover all errors (i.e. some command went wrong)
+# The tests do cover all failures (i.e. the submodule state doesn't meet the requirement)
+
+jobs:
+   run_tests:
+    runs-on: ubuntu-latest
+    name: Run All Tests
+    steps:
+    - name: Checkout Test Repo
+      uses: actions/checkout@v2
+      with:
+        repository:  jtmullen/submodule-action-test-parent
+        fetch-depth: 0
+    - name: Checkout Action
+      uses: actions/checkout@v2
+      with:
+        path: "action"
+    # Fail When Fetch Depth for Submodule too small
+    - name: Fail on Submodule Fetch Depth Small
+      uses: ./action/
+      id: sub-fetch-depth
+      continue-on-error: true
+      with:
+        path: "submodule-action-test-submodule"
+        event_path: "action/test/pr_pass_all.json"
+        require_head: true
+        branch: "main"
+        sub_fetch_depth: "1"
+    - name: Verify Fail on Submodule Fetch Depth Small
+      run: test "${{ steps.sub-fetch-depth.outputs.fails }}" = "error" 
+    # Fail on Unsupported Event Payload
+    - name: Fail on unsupported Event Payload
+      uses: ./action/
+      id: bad-payload
+      continue-on-error: true
+      with:
+        path: "submodule-action-test-submodule"
+        event_path: "action/test/bad_payload.json"
+    - name: Verify Fail on unsupported Event Payload
+      run: test "${{ steps.bad-payload.outputs.fails }}" = "error"   
+    # New Submodules should pass without a progression check
+    - name: Pass with New Submodule
+      uses: ./action/
+      id: new-submodule
+      with:
+        path: "submodule-action-test-submodule"
+        event_path: "action/test/new_submodule_event_push.json"
+        branch: "main"
+    - name: Verify Pass with New Submodule
+      run: test -z "${{ steps.new-submodule.outputs.fails }}"
+    # New submodule can fail if on wrong branch
+    - name: Fail New Submodule Wrong Branch
+      uses: ./action/
+      id: new-submodule-wrong-branch
+      continue-on-error: true
+      with:
+        path: "submodule-action-test-submodule"
+        event_path: "action/test/new_submodule_event_push.json"
+        branch: "fake_branch"
+    - name: Verify Fail New Submodule Wrong Branch
+      run: test "${{ steps.new-submodule-wrong-branch.outputs.fails }}" = "Submodule submodule-action-test-submodule Hash 803027ba35806133a1a0ecdf8fe89b7e90d1692d is not on branch fake_branch"
+    # Fail if submodule moves backwards      
+    - name: Fail When Submodule Moves Backwards
+      uses: ./action/
+      id: move-backwards
+      continue-on-error: true
+      with:
+        path: "submodule-action-test-submodule"
+        event_path: "action/test/submodule_moved_backwards.json"
+    - name: Verify Fail When Submodule Moves Backwards
+      run: test "${{ steps.move-backwards.outputs.fails }}" = "Submodule submodule-action-test-submodule on 66fe441ec6c2db7565686f303dde85d7eb8ad132 is not an ancestor of that on 1063abeafa3795cfb9f80b0b2241f961d5c8e948"
+    # Error if submodule hash is invalid (such as not pushed)
+    - name: Fail For Hash Not on Remote
+      uses: ./action/
+      id: not-on-remote
+      continue-on-error: true
+      with:
+        path: "submodule-action-test-submodule"
+        event_path: "action/test/submodule_hash_not_on_remote.json"
+    - name: Verify Fail For Hash Not on Remote
+      run: test "${{ steps.not-on-remote.outputs.fails }}" = "error"   
+    # Fail when newest required and not newest
+    - name: Fail When Newest Required
+      uses: ./action/
+      id: not-newest
+      continue-on-error: true
+      with:
+        path: "submodule-action-test-submodule"
+        event_path: "action/test/pr_no_change_to_submodule.json"
+        require_head: true
+        branch: "main"
+    - name: Verify Fail When Newest Required
+      run: test "${{ steps.not-newest.outputs.fails }}" = "Submodule submodule-action-test-submodule is not on most recent main (803027ba35806133a1a0ecdf8fe89b7e90d1692d)"
+    # Pass if unchanged on pull request
+    - name: Pass When Unchanged PR
+      uses: ./action/
+      id: pass-unchanged
+      with:
+        path: "submodule-action-test-submodule"
+        event_path: "action/test/pr_no_change_to_submodule.json"
+        require_head: true
+        branch: "main"
+        pass_if_unchanged: true
+    - name: Verify Pass When Unchanged PR
+      run: test -z "${{ steps.pass-unchanged.outputs.fails }}"
+    # Pass on PR with all requirements met
+    - name: Pass All PR
+      uses: ./action/
+      id: pass-all
+      with:
+        path: "submodule-action-test-submodule"
+        event_path: "action/test/pr_pass_all.json"
+        require_head: true
+        branch: "main"
+    - name: Verify Pass All PR
+      run: test -z "${{ steps.pass-all.outputs.fails }}"
+

README.md

@@ -3,37 +3,31 @@ A [github action](https://help.github.com/en/actions) to ensure that a submodule
 
 
 ## Inputs
-### `path`
+### `path` (required)
 The path to the submodule, this is required. Do not include leading or trailing slashes. 
-*Note: this must be the path the submodule is located at in the repo and the path to which you checkout the submodule in the workflow!*
+*Note: this must be the path the submodule is located at in the repo!*
 
-### `branch`
-The branch that the submodule version must be on. 
+### `branch` (optional)
+The name of a branch that the submodule hash must be on (after the push or on the head PR branch)
 
-This is optional, if not included the submodule will only be checked for progression, not commit presence on a specific branch. 
+### `pass_if_unchanged` (optional)
+For pull request only, if this is included the check will automatically pass if none of the commits modify the submodule. 
 
-### `pass_if_unchanged`
-If the check should automatically pass if the submodule was not changed on this branch. Only available on a PR, not a push. 
+### `fetch_depth` (optional)
+Fetch depth for the two relevant branches on a PR trigger. The action will checkout the two branches to this depth, if you know your branches are relatively short lived compared to the full history of your repo this can save you some processing time, network traffic, etc. by only checking out enough to cover your needs instead of the default full history.
 
-This is optional, if included an unchanged submodule results in automatic pass. Will be ignored if the trigger event is not a pull request. 
+### `sub_fetch_depth` (optional)
+Fetch depth for the submodule being checked. This will check out every branch to this depth. By default the full history will be checked out. I recommend leaving this at default unless your submodule is excessively large. Due to the nature of submodules there are many situations where, if the submodule is in a weird state, you will not get descriptive errors without a full fetch. 
 
-### `fetch_depth`
-Fetch depth for the two relevant branches on a PR trigger. The action will checkout the two branches to this depth, if you know your branches are relatively short lived compared to the full history of your repo this can save you some processing time, network traffic, etc. by only checking out enough to cover your needs. 
-
-This is optional, if not included it will default to full history for the branches.
-
-### `require_head`
-If the submodule is required to be on the head (most recent commit) of the specified branch. Keep in mind that it is possible that this will pass on a PR at the time it is run but no longer be on the most recent at the time of merge. 
-
-This is optional, it will not be checked if not included. Including this, but not branch, will result in an error. 
+### `require_head` (optional)
+If the submodule is required to be on the head (most recent commit) of the specified branch. Keep in mind that it is possible that this will pass on a PR at the time it is run but no longer be on the most recent at the time of merge. Branch must also be specified for this to be checked.
 
 ## Outputs
 ### `fails`
-The reason the action failed (if any). The check will stop at the first failure. 
+The reason the action failed (if any). The check will stop at the first failure. In case of an error, fails will equal "error"
 
 ## Usage
-To add to a repo create a workflow file (such as `.github/workflows/check-submodules.yml`) with the following content adjusted for your needs:
-
+To add to a repo create a workflow file (such as `.github/workflows/check-submodules.yml`) with the following content adjusted for your needs. Note that the step to checkout the submodule is only required for private submodules. 
 ```yml
 name: check-submodule
 
@@ -46,31 +40,32 @@ jobs:
     steps:
     - name: Checkout this repo
       uses: actions/checkout@v2
+    ## Step only reqired for private submodules
     - name: Checkout submodule repo
       uses: actions/checkout@v2
       with:
-        repository: UserOrOrganization/Repo
+        repository: UserOrg/RepoName
         path: "path/to/repo"
         token: ${{ secrets.PAT_for_Private_Submodule }}
-        fetch-depth: 0
     - name: Check Submodule Name
-      uses: jtmullen/submodule-branch-check-action@v0-beta
+      uses: jtmullen/submodule-branch-check-action@v1
       with:
         path: "path/to/submodule"
-        branch: "master"
+        branch: "main"
         fetch_depth: "50"
         pass_if_unchanged: true
         require_head: true
 ```
 
 ### Usage Notes
-To ensure this action runs correctly you must checkout both the current repo and the submodule repo as expected with the appropriate amount of information about the repo history included. As shown above, the [Github Checkout Action](https://github.com/actions/checkout/) is a good way to set this up. Below are the main requirements for doing so:
+To ensure this action runs correctly you must checkout the current repo. If the submodule is private, you must also check out the submodule repo, in the correct location. As shown above, the [Github Checkout Action](https://github.com/actions/checkout/) is a good way to set this up. Below are the main requirements for doing so:
+
+**Fetch Depth:** This action handles the fetch depth for both the parent repo and submodule. If you are restricting the fetch depth in this action be sure to pay attention to the default in your checkout method - you may need to restrict it there as well for the desired effect.
 
-**Fetch Depth:** This action handles the fetching (not cloning!) for the repo it is run on (checkout action does not have multibranch depth option at this time). On the submodule this will vary based on your workflow. You will need enough history for this action to determine the relationship between the submodule versions on the version being compared. If you are always working with very recent versions of the submodule this may be a small number, otherwise it could be much larger. 
+**Token:** If your submodule is private, provide a personal access token with repo level access for the submodule so it can be checked out. If not using the first party GitHub Checkout Action, ensure your method also persists the token so this action can access the remote repo.  
 
-**Token:** If your submodule is private, provide a personal access token repo level access for the submodule so it can be checked out. If not using actions/Checkout ensure your method also persists the token so this action can access the remote repo.  
+**Path:** Leave the repo the action is run on at the default location, checkout the submodule into its appropriate location within the repo. 
 
-**Path:** Leave the repo the action is run on at the default location, checkout the submodule into its appropriate location in the repo. 
 
 You can also see [where this is used](https://github.com/search?l=YAML&q=submodule-branch-check-action&type=Code)
 

action.yml

@@ -20,10 +20,18 @@ inputs:
     description: "The fetch depth for both involved branches if run on a PR"
     required: false
     default: ''
+  sub_fetch_depth:
+    description: "The fetch depth for the submodule"
+    required: false
+    default: ''  
   require_head:
     description: "If the submodule should be required to be on the head commit of the specified branch"
     required: false
     default: ''
+  event_path:
+    description: "Override the path to the github event json file. Used for testing."
+    required: false
+    default: ''
 outputs:
   fails:
     description: "Cause of failure, if run failed"