feat: add setup and fast-forward actions (#54)

README.md

@@ -28,10 +28,35 @@ If run outside a GitHub repository, then the `--owner` and `--repo` flags are re
 
 All configuration may be passed via environment variable rather than flag. The environment variable associated with each flag is `GHUP_[UPPERCASED_FLAG_NAME]`, e.g. `GHUP_TOKEN`, `GHUP_OWNER`, `GHUP_REPO`, `GHUP_BRANCH`, `GHUP_AUTHOR_TRAILER`, etc.
 
-In addition, various fallback environment variables are supported for better integration with Jenkins and similar CI tools: `GITHUB_OWNER`, `GITHUB_TOKEN`, `CHANGE_BRANCH`, `BRANCH_NAME`, `GIT_BRANCH`, `GIT_COMMITTER_NAME`, `GIT_COMMITTER_EMAIL`, etc.
+In addition, various fallback environment variables are supported for better integration with Jenkins and similar CI tools: `GITHUB_TOKEN`, `GITHUB_OWNER`, `GITHUB_REPO`, `CHANGE_BRANCH`, `BRANCH_NAME`, `GIT_BRANCH`, `GIT_COMMITTER_NAME`, `GIT_COMMITTER_EMAIL`, etc.
+
+The environment variable `GITHUB_REPOSITORY`, always set in GitHub Actions workflow context in the form `<owner>/<repo>`, is only used to set initial defaults for `--owner` and `--repo`, but will be overridden by local repository context and more specific configuration.
+If `GITHUB_REPOSITORY` is set, then `--branch` will also default from `GITHUB_HEAD_REF` in pull request context, or `GITHUB_REF_NAME` otherwise.
 
 For security, it is strongly recommended that the GitHub Token by passed via environment (`GHUP_TOKEN` or `GITHUB_TOKEN`) or file path (`--token /path/to/token-file`, `--token <(gh auth token)` or `export GHUP_TOKEN=/path/to/token-file ghup …`)
 
+## Installation
+
+### Generic
+
+Binaries for all supported platforms and architectures are available from [GitHub Releases](https://github.com/nexthink-oss/ghup/releases/latest).
+
+Alternatively, install to `$GOBIN` with a local Go toolchain:
+
+```sh
+go install github.com/nexthink-oss/ghup@latest
+```
+
+### Homebrew
+
+```sh
+brew install isometry/tap/ghup
+```
+
+### GitHub Actions
+
+The [`nexthink-oss/ghup/actions/setup`](actions/setup/) action is available to make the `ghup` tool available in GitHub Actions.
+
 ## Usage
 
 ### Content
@@ -199,43 +224,21 @@ Note: the `--branch`, `--message` and trailer-related flags are not used by the
 
 ```console
 $ ghup update-ref -s staging heads/production
-source:
-  ref: heads/staging
-  sha: 206e1a484f03cd320a2125a50aa73bd8a2b045dc
-target:
-  - ref: heads/production
-    updated: true
-    old_sha: b7ccc4db9bc43551fd3571c260869f4c69aa2fd4
-    sha: 206e1a484f03cd320a2125a50aa73bd8a2b045dc
+{"source":{"ref":"heads/staging","sha":"206e1a484f03cd320a2125a50aa73bd8a2b045dc"},"target":[{"ref":"heads/production","updated":true,"old_sha":"b7ccc4db9bc43551fd3571c260869f4c69aa2fd4","sha":"206e1a484f03cd320a2125a50aa73bd8a2b045dc"}]}
 ```
 
 ##### Create a lightweight tag pointing at a specific commit
 
 ```console
 $ ghup update-ref -s b7ccc4d example
-source:
-  ref: b7ccc4d
-  sha: b7ccc4db9bc43551fd3571c260869f4c69aa2fd4
-target:
-  - ref: tags/example
-    updated: true
-    sha: b7ccc4db9bc43551fd3571c260869f4c69aa2fd4
+{"source":{"ref":"b7ccc4d","sha":"b7ccc4db9bc43551fd3571c260869f4c69aa2fd4"},"target":[{"ref":"tags/example","updated":true,"sha":"b7ccc4db9bc43551fd3571c260869f4c69aa2fd4"}]}
 ```
 
 ##### Update GitHub Actions-style major and minor tags following patch release:
 
 ```console
 $ ghup update-ref -s tags/v1.1.7 v1.1 v1
-source:
-  ref: tags/v1.1.7
-  sha: b7ccc4db9bc43551fd3571c260869f4c69aa2fd4
-target:
-  - ref: tags/v1.1
-    updated: true
-    sha: b7ccc4db9bc43551fd3571c260869f4c69aa2fd4
-  - ref: tags/v1
-    updated: true
-    sha: b7ccc4db9bc43551fd3571c260869f4c69aa2fd4
+{"source":{"ref":"tags/v1.1.7","sha":"b7ccc4db9bc43551fd3571c260869f4c69aa2fd4"},"target":[{"ref":"tags/v1.1","updated":true,"sha":"b7ccc4db9bc43551fd3571c260869f4c69aa2fd4"},{"ref":"tags/v1","updated":true,"sha":"b7ccc4db9bc43551fd3571c260869f4c69aa2fd4"}]}
 ```
 
 ### Debug Info
@@ -244,16 +247,19 @@ In order to better validate the configuration derived from context (working dire
 
 ```console
 $ ghup info
-hasToken: true
-trailers:
-  - 'Co-Authored-By: Example User <[email protected]>'
-owner: nexthink-oss
-repository: ghup
-branch: feature/branch
-commit: 5e1692253399bd9ea6077dba27e4cdc8a15b9720
-isClean: false
-commitMessage:
-  headline: Commit via API
-  body: |2-
-    Co-Authored-By: Example User <[email protected]>
+{
+  "has_token": true,
+  "owner": "nexthink-oss",
+  "repository": "ghup",
+  "branch": "feature/branch",
+  "commit": "5e1692253399bd9ea6077dba27e4cdc8a15b9720",
+  "clean": false,
+  "message": {
+    "headline": "Commit via API",
+    "body": "Co-Authored-By: Example User <[email protected]>"
+  }
+  "trailers": [
+    "Co-Authored-By: Example User <[email protected]>"
+  ],
+}
 ```

actions/fast-forward/.gitignore

@@ -0,0 +1 @@
+node_modules

actions/fast-forward/.node-version

@@ -0,0 +1 @@
+20.10.0

actions/fast-forward/README.md

@@ -0,0 +1,71 @@
+# `fast-forward` action
+
+The `nexthink-oss/ghup/actions/fast-forward` action will fast-forward one or more `target` refs (heads or tags) to match `source`.
+
+It can be used, for example, to create/update tags or to implement true fast-forward merge for GitHub PRs.
+
+## Inputs
+
+### `source` input
+
+**Required** a ref-or-commit from which to source the target commit.
+
+### `target` input
+
+**Required** a newline-separated list of targets to update to the resolved source commit.
+
+### `force` input
+
+**Optional** force update target heads even if fast-forward is not possible. Default: `false`
+
+### `version` input
+
+**Optional** version of `ghup` to install (default: `latest`)
+
+## Outputs
+
+### `source` output
+
+Resolved source details.
+
+### `target` output
+
+Target update details.
+
+### `version`
+
+The version of `ghup` actually installed.
+
+## Example usage
+
+```yaml
+name: release-to-environment
+
+on:
+  workflow_dispatch:
+    inputs:
+      revision:
+        description: 'Ref-or-commit to release'
+        type: string
+        default: heads/main
+      environment:
+        description: 'Environment to update'
+        type: environment
+        required: true
+
+permissions:
+  contents: write
+
+jobs:
+  release-to-environment:
+    runs-on: ubuntu-latest
+    environment: ${{ inputs.environment }}
+    steps:
+      - name: Update Environment Tag
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+        uses: nexthink-oss/ghup/actions/fast-forward
+        with:
+          source: ${{ inputs.revision }}
+          target: tags/${{ inputs.environment }}
+```

actions/fast-forward/action.yaml

@@ -0,0 +1,26 @@
+name: ghup/fast-forward
+description: "Fast-forward target ref to source"
+author: "Nexthink"
+inputs:
+  source:
+    description: "Source ref-or-commit HEAD"
+    required: true
+  target:
+    description: "Refs to fast-forward to match source (newline-separated)"
+    required: true
+  force:
+    description: "Force push to target"
+    required: false
+    default: "false"
+  version:
+    description: "Version of ghup to use"
+    required: false
+    default: "latest"
+outputs:
+  source:
+    description: "Resolved source details"
+  target:
+    description: "Updated target details"
+runs:
+  using: "node20"
+  main: "dist/index.js"