Add optional ref arg for branch to pull (#824)

Signed-off-by: Alex Moriarty <alex.moriarty@picknik.ai>

README.md

@@ -103,6 +103,33 @@ steps:
       vcs-repo-file-url: https://raw.githubusercontent.com/ros2/ros2/humble/ros2.repos
 ```
 
+### Schedule an action on a specific branch
+
+If you want to continue supporting older ROS releases while developing on an the main branch use `acton-ros-ci` with `ref` on a scheduled job.
+Without setting ref the default branch and most recent commit will be used.
+
+```yaml
+name: Humble Source Build
+on:
+  schedule:
+    # At 00:00 on Sunday.
+    - cron '0 0 * * 0'
+
+jobs:
+  humble_source:
+    runs_on: ubuntu-22.04
+    steps:
+      - uses: ros-tooling/setup-ros@v0.6
+        with:
+          required-ros-distributions: humble
+      - uses: ros-tooling/action-ros-ci@v0.3
+        with:
+          package-name: my_package
+          ref: humble
+          target-ros2-distro: humble
+          vcs-repo-file-url: https://raw.githubusercontent.com/ros2/ros2/humble/ros2.repos
+```
+
 ### Build with a custom `repos` or `rosinstall` file
 
 You can specify your own repos file using the `vcs-repo-file-url` input.

action.yml

@@ -84,6 +84,14 @@ inputs:
       Passing multiple keys is allowed.
       Keys names can be separated by any whitespace character.
     required: false
+  ref:
+    default: ""
+    description: |
+      Branch or reference to checkout via vcstool.
+      If unset will use the branch from where this action was triggered.
+      Scheduled events default to latest commit of default branch.
+      Set this if you want the scheduled job to run on on a specific branch.
+    required: false
 outputs:
   ros-workspace-directory-name:
     description: |

dist/index.js

@@ -11550,7 +11550,9 @@ done`;
             repoFullName = github.context.payload.pull_request.head.repo.full_name;
         }
         const headRef = process.env.GITHUB_HEAD_REF;
-        const commitRef = headRef || github.context.sha;
+        let commitRef = headRef || github.context.sha;
+        // if ref is set this overrides anything calculated above
+        commitRef = core.getInput("ref") || commitRef;
         const repoFilePath = path.join(rosWorkspaceDir, "package.repo");
         // Add a random string prefix to avoid naming collisions when checking out the test repository
         const randomStringPrefix = Math.random().toString(36).substring(2, 15);

src/action-ros-ci.ts

@@ -559,7 +559,9 @@ done`;
 		repoFullName = github.context.payload.pull_request.head.repo.full_name;
 	}
 	const headRef = process.env.GITHUB_HEAD_REF as string;
-	const commitRef = headRef || github.context.sha;
+	let commitRef = headRef || github.context.sha;
+	// if ref is set this overrides anything calculated above
+	commitRef = core.getInput("ref") || commitRef;
 	const repoFilePath = path.join(rosWorkspaceDir, "package.repo");
 	// Add a random string prefix to avoid naming collisions when checking out the test repository
 	const randomStringPrefix = Math.random().toString(36).substring(2, 15);