fa-harness-tools 1.0.4 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a3cee0250f6a943fb938d11c0e118f53d26ea03be5edb7e8f8fc7fb0f73e154e
-  data.tar.gz: 030ab9dac48945eac8366a8cfcbafecc4bbbeebc5dc16254f97bfa3cfdb26368
+  metadata.gz: ab0431cf2bbd5ebb8988790fd5336b93e11880d6fa3be07d1c580192d9a9aca3
+  data.tar.gz: 729256cfb4d548df271c156ef1ae60486c379fe40cee2d38cb4ef0c792283b0d
 SHA512:
-  metadata.gz: 3f00171760572605f0282595bc852bf20181768464dd9811051cb71a6658daa9692bdb77c46dbb180eca6c982b17736cf0f4c24e89cf6fba60fcddd379d81a08
-  data.tar.gz: 863db5b6b4230a1d2fedd00ab20f05d830fb682bc9b4947f1e4bdd69429dfa90ba637fac2afabd6cd7c8c7b71271e6a53346593325e46a0c7c6377453c86e7bd
+  metadata.gz: 86068a39f783c7f91754cd3a116e5bcef456b03c33f71b066e86203d6c1c3ba52766c63a6af36a5b63890e8e062db5f0fce5fad6ff0e6a732297f9d39824c363
+  data.tar.gz: 60a571e75deb4f9c828ec3dbec4993eab017ea4f11f99afb7ed97430e3f933ab4605d6df7334963969985b086288068caf385278c91d48a58b11df4bf6c68884

data/.github/workflows/reviewdog.yml

@@ -0,0 +1,13 @@
+name: reviewdog
+on: [pull_request]
+jobs:
+  actionlint:
+    name: runner / actionlint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - name: actionlint
+        uses: reviewdog/action-actionlint@v1.2.0
+        with:
+          fail_on_error: true
+          reporter: github-pr-review

data/.github/workflows/ruby.yml

@@ -1,20 +1,43 @@
-name: Ruby
+name: CICD
 
 on: [push, pull_request]
 
 jobs:
-  build:
+  test:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v1
+      - name: Set up Ruby 2.5
+        uses: actions/setup-ruby@v1
+
+      - name: Build and test with Rake
+        run: |
+          gem install bundler -v 1.16.4
+          bundle install --jobs 4 --retry 3
+          bundle exec rake
 
+  release:
+    needs: test
     runs-on: ubuntu-latest
+    if: ${{ github.ref == 'refs/heads/master' }}
 
     steps:
-    - uses: actions/checkout@v1
-    - name: Set up Ruby 2.5
-      uses: actions/setup-ruby@v1
-      with:
-        ruby-version: 2.5.x
-    - name: Build and test with Rake
-      run: |
-        gem install bundler -v 1.16.4
-        bundle install --jobs 4 --retry 3
-        bundle exec rake
+      - uses: actions/checkout@v2
+      - uses: ruby/setup-ruby@v1 # .ruby-version
+        with:
+          bundler-cache: true    # bundle install
+
+      - run: bundle exec rake build
+
+      - uses: fac/ruby-gem-setup-credentials-action@v2
+        with:
+          user: ""
+          key: rubygems
+          token: ${{ secrets.FAC_RUBYGEMS_KEY }}
+
+      - uses: fac/ruby-gem-push-action@v2
+        with:
+          user: ""
+          key: rubygems
+          token: ${{ secrets.FAC_RUBYGEMS_KEY }}

data/Gemfile.lock

@@ -1,25 +1,53 @@
 PATH
   remote: .
   specs:
-    fa-harness-tools (1.0.4)
+    fa-harness-tools (1.3.0)
+      fugit (~> 1.3)
       octokit (~> 4.0)
+      pastel (~> 0.7)
       tzinfo (~> 2.0)
       tzinfo-data (~> 1.0)
 
 GEM
   remote: https://rubygems.org/
   specs:
-    addressable (2.7.0)
+    addressable (2.8.0)
       public_suffix (>= 2.0.2, < 5.0)
-    concurrent-ruby (1.1.5)
+    concurrent-ruby (1.1.9)
     diff-lcs (1.3)
-    faraday (0.17.0)
+    et-orbi (1.2.5)
+      tzinfo
+    faraday (1.8.0)
+      faraday-em_http (~> 1.0)
+      faraday-em_synchrony (~> 1.0)
+      faraday-excon (~> 1.1)
+      faraday-httpclient (~> 1.0.1)
+      faraday-net_http (~> 1.0)
+      faraday-net_http_persistent (~> 1.1)
+      faraday-patron (~> 1.0)
+      faraday-rack (~> 1.0)
       multipart-post (>= 1.2, < 3)
+      ruby2_keywords (>= 0.0.4)
+    faraday-em_http (1.0.0)
+    faraday-em_synchrony (1.0.0)
+    faraday-excon (1.1.0)
+    faraday-httpclient (1.0.1)
+    faraday-net_http (1.0.1)
+    faraday-net_http_persistent (1.2.0)
+    faraday-patron (1.0.0)
+    faraday-rack (1.0.0)
+    fugit (1.5.2)
+      et-orbi (~> 1.1, >= 1.1.8)
+      raabro (~> 1.4)
     multipart-post (2.1.1)
-    octokit (4.14.0)
+    octokit (4.21.0)
+      faraday (>= 0.9)
       sawyer (~> 0.8.0, >= 0.5.3)
-    public_suffix (4.0.1)
-    rake (10.5.0)
+    pastel (0.8.0)
+      tty-color (~> 0.5)
+    public_suffix (4.0.6)
+    raabro (1.4.0)
+    rake (13.0.1)
     rspec (3.9.0)
       rspec-core (~> 3.9.0)
       rspec-expectations (~> 3.9.0)
@@ -33,13 +61,15 @@ GEM
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.9.0)
     rspec-support (3.9.0)
+    ruby2_keywords (0.0.5)
     sawyer (0.8.2)
       addressable (>= 2.3.5)
       faraday (> 0.8, < 2.0)
     timecop (0.9.1)
-    tzinfo (2.0.0)
+    tty-color (0.6.0)
+    tzinfo (2.0.4)
       concurrent-ruby (~> 1.0)
-    tzinfo-data (1.2019.3)
+    tzinfo-data (1.2021.1)
       tzinfo (>= 1.0.0)
 
 PLATFORMS
@@ -48,9 +78,9 @@ PLATFORMS
 DEPENDENCIES
   bundler (~> 1.0)
   fa-harness-tools!
-  rake (~> 10.0)
+  rake (~> 13.0)
   rspec (~> 3.8)
   timecop (~> 0.9)
 
 BUNDLED WITH
-   1.16.4
+   1.17.2

data/README.md

@@ -1,5 +1,7 @@
 # fa-harness-tools
 
+#### https://rubygems.org/gems/fa-harness-tools
+
 FreeAgent-specific pre-flight checks and tools that are designed to work in [Harness](https://harness.io).
 
 ## Installation
@@ -22,9 +24,11 @@ Or install it yourself as:
 
 Examples below use [variables defined by Harness](https://docs.harness.io/article/9dvxcegm90-variables) so should be suitable to use directly in Harness scripts.
 
-### Required environment variables
+Full scripts that can be used in Harness are available in the [examples/](examples/) directory.
+
+### Optional environment variables
 
-* `GITHUB_OAUTH_TOKEN` must be exported, containing a valid [personal access token](https://help.github.com/en/github/authenticating-to-github/creating-a-personal-access-token-for-the-command-line) for GitHub
+* To access private repositories, `GITHUB_OAUTH_TOKEN` must be exported, containing a valid [personal access token](https://help.github.com/en/github/authenticating-to-github/creating-a-personal-access-token-for-the-command-line) for GitHub
 
 ### check-branch-brotection
 
@@ -80,7 +84,9 @@ After checking out the repo, run `bin/setup` to install dependencies. You can al
 
 To install this gem onto your local machine, run `bundle exec rake install`.
 
-To release a new version, update the version number in `version.rb`, run `bundle` and commit the version bump. Then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+To release a new version, update the version number in `version.rb`. After your PR is merged to master, the CICD GitHub Action workflow will release to RubyGems automatically:
+Gem is hosted publicly here:
+https://rubygems.org/gems/fa-harness-tools
 
 The Ruby version used matches the one from the `harness/delegate` Docker image.
 

data/examples/create-deployment-tag/README.md

@@ -0,0 +1,17 @@
+# Create deployment Git tags
+
+## Purpose
+
+Can be added to a Harness pipeline to add a Git tag on every deployment. The tags can then be used by the other pre-flight checks.
+
+## Requirements
+
+1. Add a GitHub OAuth token to the Harness secrets manager, named `github-oauth-token`
+2. Assumes the artifact build number is the commit ID
+3. fa-harness-tools is installed on the Harness delegates (`gem install -v $VERSION fa-harness-tools`)
+
+## Installation
+
+Add the script to the Harness template library and then add to the last phase of the deployment workflow.
+
+Define the `ONLY_ENVIRONMENT` variable input on the template, defaulting to `false`.

data/examples/create-deployment-tag/create-deployment-tag.sh

@@ -0,0 +1,19 @@
+#!/bin/bash
+#
+# Creates a Git tag to mark successful deployment with fa-harness-tools
+#
+# Optionally set ONLY_ENVIRONMENT to only tag when running a deployment in
+# that Harness environment.
+
+set -e
+
+export GITHUB_OAUTH_TOKEN="${secrets.getValue("github-oauth-token")}"
+
+if [ -z "${ONLY_ENVIRONMENT}" -o "${ONLY_ENVIRONMENT}" = "${env.name}" ]; then
+  create-deployment-tag \
+    --build-no "${artifact.buildNo}" \
+    --environment "${env.name}" \
+    --repository "${artifact.source.repositoryName}" \
+    --tagger-email "noreply@example.com" \
+    --tagger-name "Harness"
+fi

data/examples/production-preflight-checks/README.md

@@ -0,0 +1,20 @@
+# Production pre-flight checks
+
+## Purpose
+
+Can be added to a Harness pipeline to enforce a set of strict requirements for production deployments:
+
+1. Only deploy within the daily deployment window/schedule
+2. Only deploy builds from the master branch
+3. Automated (triggered) deployments may only deploy forwards
+4. Manual deployments may only deploy forwards or roll back three deployments
+
+## Requirements
+
+1. Add a GitHub OAuth token to the Harness secrets manager, named `github-oauth-token`
+2. Assumes the artifact build number is the commit ID
+3. fa-harness-tools is installed on the Harness delegates (`gem install -v $VERSION fa-harness-tools`)
+
+## Installation
+
+Add the script to the Harness template library and then add to an early phase of the deployment workflow.

data/examples/production-preflight-checks/production-preflight-checks.sh

@@ -0,0 +1,35 @@
+#!/bin/bash
+#
+# Runs production deployment checks from fa-harness-tools
+
+set -e
+
+export GITHUB_OAUTH_TOKEN="${secrets.getValue("github-oauth-token")}"
+
+run() {
+  CMD=$1
+  shift
+  echo
+  $CMD \
+    --build-no "${artifact.buildNo}" \
+    --environment "${env.name}" \
+    --repository "${artifact.source.repositoryName}" \
+    "$@"
+  echo
+}
+
+# 1. Check we're within the daily deployment schedule
+check-schedule
+
+# 2. Check the commit is on the master branch
+run check-branch-protection
+
+if [[ "${deploymentTriggeredBy}" =~ "Deployment Trigger" ]]; then
+  # 3. For automated deployments (trigger from CI), check deployment is fast-forward
+  run check-forward-deploy
+else
+  # 3. For user deployments, check deployment is fast-forward or within last three deployments for rollbacks
+  run check-recent-deploy --allowed-rollback-count 3
+fi
+
+exit 0

data/exe/check-branch-protection

@@ -32,7 +32,7 @@ OptionParser.new do |opts|
 end.parse!
 
 client = FaHarnessTools::GithubClient.new(
-  oauth_token: ENV.fetch("GITHUB_OAUTH_TOKEN"),
+  oauth_token: ENV.fetch("GITHUB_OAUTH_TOKEN", nil),
   owner: options.fetch(:github_owner),
   repo: options.fetch(:repo),
 )
@@ -48,10 +48,4 @@ result = FaHarnessTools::CheckBranchProtection.new(
   branch: options.fetch(:branch),
 ).verify?
 
-if result.first
-  puts result.last
-  exit 0
-else
-  $stderr.puts result.last
-  exit 1
-end
+exit result ? 0 : 1

data/exe/check-forward-deploy

@@ -48,10 +48,4 @@ result = FaHarnessTools::CheckForwardDeploy.new(
   tag_prefix: options.fetch(:tag_prefix),
 ).verify?
 
-if result.first
-  puts result.last
-  exit 0
-else
-  $stderr.puts result.last
-  exit 1
-end
+exit result ? 0 : 1

data/exe/check-recent-deploy

@@ -54,10 +54,4 @@ result = FaHarnessTools::CheckRecentDeploy.new(
   allowed_rollback_count: options.fetch(:allowed_rollback_count),
 ).verify?
 
-if result.first
-  puts result.last
-  exit 0
-else
-  $stderr.puts result.last
-  exit 1
-end
+exit result ? 0 : 1

data/exe/check-schedule

@@ -3,17 +3,31 @@
 require "fa-harness-tools"
 require "optparse"
 
-options = {}
+options = {
+  schedules: [],
+  timezone: "Europe/London",
+}
 OptionParser.new do |opts|
   opts.banner = "Usage: check-schedule [options]"
-end.parse!
 
-result = FaHarnessTools::CheckSchedule.new.verify?
+  opts.on("--schedule CRON", "Schedule defines a window in which a deployment can take place. Accepts cron syntax, e.g. '* 9-15 * * mon-thu'") do |v|
+    options[:schedules] << v
+  end
+
+  opts.on("--timezone TIMEZONE", "Specify the timezone which the schedule will be checked in, e.g. 'Europe/London'") do |v|
+    options[:timezone] = v
+  end
+end.parse!
 
-if result.first
-  puts result.last
-  exit 0
-else
-  $stderr.puts result.last
-  exit 1
+def schedules(options)
+  if options[:schedules].length == 0
+    options[:schedules] = [
+      "* 9-15 * * mon-fri",
+    ]
+  end
+  options[:schedules].map { |schedule| FaHarnessTools::Schedule.new(schedule: schedule.to_s) }
 end
+
+result = FaHarnessTools::CheckSchedule.new(timezone: options[:timezone], schedules: schedules(options)).verify?
+
+exit result ? 0 : 1

data/fa-harness-tools.gemspec

@@ -16,6 +16,7 @@ Gem::Specification.new do |spec|
   spec.metadata["homepage_uri"] = spec.homepage
   spec.metadata["source_code_uri"] = spec.homepage
   spec.metadata["changelog_uri"] = "https://github.com/fac/fa-harness-tools/releases"
+  spec.metadata['allowed_push_host'] = "https://rubygems.org"
 
   # Specify which files should be added to the gem when it is released.
   # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
@@ -27,11 +28,13 @@ Gem::Specification.new do |spec|
   spec.require_paths = ["lib"]
 
   spec.add_runtime_dependency "octokit", "~> 4.0"
+  spec.add_runtime_dependency "pastel", "~> 0.7"
   spec.add_runtime_dependency "tzinfo", "~> 2.0"
   spec.add_runtime_dependency "tzinfo-data", "~> 1.0"
+  spec.add_runtime_dependency "fugit", "~> 1.3"
 
   spec.add_development_dependency "bundler", "~> 1.0"
-  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "rake", "~> 13.0"
   spec.add_development_dependency "rspec", "~> 3.8"
   spec.add_development_dependency "timecop", "~> 0.9"
 end

data/lib/fa-harness-tools/check_branch_protection.rb

@@ -5,14 +5,23 @@ module FaHarnessTools
       @client = client
       @context = context
       @branch = branch
+      @logger = CheckLogger.new(
+        name: "Check branch protection",
+        description: "Only allow commits on the #{@branch} branch to be deployed",
+      )
     end
 
     def verify?
+      @logger.start
+      @logger.context_info(@client, @context)
+
       new_sha = @context.new_commit_sha
+
+      @logger.info("checking if #{@branch} branch contains the commit")
       if @client.branch_contains?(@branch, new_sha)
-        [true, "#{@branch} contains #{new_sha}"]
+        @logger.pass "#{@branch} contains #{new_sha}"
       else
-        [false, "#{@branch} does not contain #{new_sha}"]
+        @logger.fail "#{@branch} does not contain #{new_sha}"
       end
     end
   end

data/lib/fa-harness-tools/check_forward_deploy.rb

@@ -13,25 +13,36 @@ module FaHarnessTools
       @client = client
       @context = context
       @tag_prefix = tag_prefix
+      @logger = CheckLogger.new(
+        name: "Check forward deploy",
+        description: "Only allow deployments that are newer than what's currently deployed",
+      )
     end
 
     def verify?
+      @logger.start
+      @logger.context_info(@client, @context)
+
       current_tag = @client.last_deploy_tag(
         prefix: @tag_prefix, environment: @context.environment)
 
       if current_tag.nil?
         # If no previous deploys we need to let it deploy otherwise it will
         # never get past this check!
-        return true, "first deploy"
+        @logger.info "no #{@tag_prefix} tag was found, so this must be the first deployment"
+        return @logger.pass("this is the first recorded deployment so is permitted")
       end
 
+      @logger.info("the most recent deployment is #{current_tag[:name]}")
+
       current_deployed_rev = current_tag[:commit][:sha]
       rev = @context.new_commit_sha
+      @logger.info("which means the currently deployed commit is #{current_deployed_rev}")
 
       if @client.is_ancestor_of?(current_deployed_rev, rev)
-        [true, "forward deploy, #{rev} is ahead of #{current_deployed_rev}"]
+        @logger.pass "the commit being deployed is more recent than the currently deployed commit"
       else
-        [false, "not a forward deploy, #{rev} is behind #{current_deployed_rev}"]
+        @logger.fail "the commit being deployed is before the currently deployed commit, so would revert changes"
       end
     end
   end

data/lib/fa-harness-tools/check_logger.rb

@@ -0,0 +1,34 @@
+require "pastel"
+
+module FaHarnessTools
+  class CheckLogger
+    def initialize(name:, description:)
+      @name = name
+      @description = description
+      @pastel = Pastel.new(enabled: true)
+    end
+
+    def start
+      puts @pastel.cyan(@pastel.bold(@name), %{ (#{@description})})
+    end
+
+    def info(message)
+      puts "  ... #{message}"
+    end
+
+    def context_info(client, context)
+      info("we're deploying repo #{client.owner_repo} into environment #{context.environment}")
+      info("we're trying to deploy commit #{context.new_commit_sha}")
+    end
+
+    def pass(message)
+      puts @pastel.green("PASS: #{message}")
+      true
+    end
+
+    def fail(message)
+      puts @pastel.red("FAIL: #{message}")
+      false
+    end
+  end
+end

data/lib/fa-harness-tools/check_recent_deploy.rb

@@ -27,9 +27,16 @@ module FaHarnessTools
       @context = context
       @tag_prefix = tag_prefix
       @allowed_rollback_count = allowed_rollback_count
+      @logger = CheckLogger.new(
+        name: "Check recent deploys",
+        description: "Only allow deployments of recent commits, up to #{@allowed_rollback_count} deployment rollbacks",
+      )
     end
 
     def verify?
+      @logger.start
+      @logger.context_info(@client, @context)
+
       tags = @client.
         all_deploy_tags(prefix: @tag_prefix, environment: @context.environment).
         sort_by { |tag| tag[:name] }
@@ -39,16 +46,20 @@ module FaHarnessTools
       if latest_allowed_tag.nil?
         # If no previous deploys we need to let it deploy otherwise it will
         # never get past this check!
-        return true, "first deploy"
+        @logger.info "no #{@tag_prefix} tag was found, so this must be the first deployment"
+        return @logger.pass("this is the first recorded deployment so is permitted")
       end
 
-      latest_allowed_rev = latest_allowed_tag[:commit][:sha]
+      @logger.info("the most recent tag allowed is #{latest_allowed_tag[:name]}")
+
+      latest_allowed_rev = @client.get_commit_sha_from_tag(latest_allowed_tag)
       rev = @context.new_commit_sha
+      @logger.info("which means the most recent commit allowed is #{latest_allowed_rev}")
 
       if @client.is_ancestor_of?(latest_allowed_rev, rev)
-        [true, "#{rev} is ahead of no.#{@allowed_rollback_count} most recent commit with #{@tag_prefix.inspect} tag"]
+        @logger.pass "the commit being deployed is more recent than the last permitted rollback commit"
       else
-        [false, "#{rev} is prior to no.#{@allowed_rollback_count} most recent commit with #{@tag_prefix.inspect} tag"]
+        @logger.fail "the commit being deployed is older than the last permitted rollback commit"
       end
     end
   end

data/lib/fa-harness-tools/check_schedule.rb

@@ -3,28 +3,35 @@ require "tzinfo"
 
 module FaHarnessTools
   # Check against the time of day so you can restrict deploying to sensible
-  # hours. Uses local London time by default.
-  #
-  # Restricts to Mon-Thu from 9am to 4pm, Fri from 9am to 12pm.
+  # hours.
   class CheckSchedule
-    def initialize(timezone: "Europe/London")
+    def initialize(timezone:, schedules:)
       tz = TZInfo::Timezone.get(timezone)
+      @timezone = timezone
       @now = tz.to_local(Time.now.utc)
+      @schedules = schedules
+      @logger = CheckLogger.new(
+        name: "Check deployment schedule",
+        description: "Only allow deployments within certain times of the day",
+      )
     end
 
     def verify?
-      permitted = false
-      case @now.wday
-      when 1..4
-        permitted = true if @now.hour >= 9 && @now.hour < 16
-      when 5
-        permitted = true if @now.hour >= 9 && @now.hour < 12
+      @logger.start
+      @logger.info("operating in the #{@timezone} timezone")
+      @logger.info("local time is #{@now}")
+
+      permitted = @schedules.any? do |schedule|
+        can_run = schedule.can_run?(time: @now)
+        @logger.info("deployments are allowed due to the following schedule: #{schedule.to_s}") if can_run
+        can_run
       end
 
       if permitted
-        [true, "scheduled deploy time"]
+        @logger.pass "inside the deployment schedule"
       else
-        [false, "outside deployment schedule"]
+        @logger.info "failed to match any schedule #{@schedules.map(&:to_s).join(", ")}"
+        @logger.fail "outside the deployment schedule"
       end
     end
   end

data/lib/fa-harness-tools/github_client.rb

@@ -9,6 +9,8 @@ module FaHarnessTools
       @octokit = Octokit::Client.new(access_token: oauth_token)
       @owner = owner
       @repo = repo
+      @oauth_token = oauth_token
+      validate_repo
     end
 
     def owner_repo
@@ -17,17 +19,24 @@ module FaHarnessTools
 
     # Return all tags starting "harness-deploy-ENV-"
     #
-    # Used to find deployments in an environment. The commit SHA of the tag is
-    # in [:commit][:sha] in the returned hash.
+    # Used to find deployments in an environment. Provides only the tag name
+    # and object, though that may be an annotated tag or a commit.
+    #
+    # Use #get_commit_sha_from_tag to reliably find the commit that a tag
+    # points to.
     #
     # @return [Array[Hash]] Array of tag data hash, or [] if none
     def all_deploy_tags(prefix:, environment:)
-      @octokit.auto_paginate = true
-      @octokit.tags(owner_repo).find_all do |tag|
-        tag[:name].start_with?("#{prefix}-#{environment}-")
+      # #refs is a much quicker way than #tags to pull back all tag names, so
+      # we prefer this and then fetch commit information only when we need it
+      @octokit.refs(owner_repo, "tags/#{prefix}-#{environment}-").map do |ref|
+        {
+          name: ref[:ref][10..-1], # remove refs/tags/ prefix
+          object: ref[:object],
+        }
       end
-    ensure
-      @octokit.auto_paginate = false
+    rescue Octokit::NotFound
+      []
     end
 
     # Return the last (when sorted) tag starting "harness-deploy-ENV-"
@@ -39,7 +48,11 @@ module FaHarnessTools
     def last_deploy_tag(prefix:, environment:)
       last_tag = all_deploy_tags(prefix: prefix, environment: environment).
         sort_by { |tag| tag[:name] }.last
-      last_tag ? last_tag : nil
+      return nil unless last_tag
+
+      last_tag.merge(
+        commit: { sha: get_commit_sha_from_tag(last_tag) },
+      )
     end
 
     # Return a full commit SHA from a short SHA
@@ -52,20 +65,48 @@ module FaHarnessTools
       commit[:sha]
     end
 
+    # Return a full commit SHA from a tag
+    #
+    # The `tag` argument should be a Hash of tag data with an :object that can
+    # either be an annotated tag or a commit object.
+    #
+    # @return [String] Full commit SHA
+    # @raise [LookupError] If tag cannot be found
+    def get_commit_sha_from_tag(tag)
+      case tag[:object][:type]
+      when "commit"
+        tag[:object][:sha]
+      when "tag"
+        # When a tag points to a tag, recurse into it until we find a commit object
+        refed_tag = @octokit.tag(owner_repo, tag[:object][:sha])
+        get_commit_sha_from_tag(refed_tag.to_h.merge(tag.slice(:name)))
+      else
+        raise LookupError, "Tag #{tag[:name]} points to a non-commit object (#{tag[:object].inspect})"
+      end
+    rescue Octokit::NotFound
+      raise LookupError, "Unable to find tag #{tag.inspect} in Git repo"
+    end
+
     # Checks if <ancestor> is an ancestor of <commit>
     #
     # i.e. commit and ancestor are directly related
     #
     # @return [Bool] True is <ancestor> is ancestor of <commit>
     def is_ancestor_of?(ancestor, commit)
-      !!find_commit(commit) { |c| c[:sha] == ancestor }
+      # Compare returns the merge base, the common point in history between the
+      # two commits. If X is the ancestor of Y, then the merge base must be X.
+      # If not, it's a different branch.
+      @octokit.compare(owner_repo, ancestor, commit)[:merge_base_commit][:sha] == get_commit_sha(ancestor)
     end
 
     # Checks if <commit> is on branch <branch>
     #
     # @return [Bool] True is <commit> is on <branch>
     def branch_contains?(branch, commit)
-      !!find_commit(branch) { |c| c[:sha] == commit }
+      # The same implementation works for this question. We have both methods
+      # to make the intent clearer and also this one is guaranteed to resolve a
+      # branch name for the first argument.
+      is_ancestor_of?(commit, branch)
     end
 
     # Creates a Git tag
@@ -79,16 +120,15 @@ module FaHarnessTools
 
     private
 
-    # Paginate over commits from a given sha/branch, and exit early if the
-    # supplied block matches
-    def find_commit(sha_or_branch, &block)
-      result = @octokit.commits(owner_repo, sha_or_branch).find(&block)
-      response = @octokit.last_response
-      until result || !response.rels[:next]
-        response = response.rels[:next].get
-        result = response.data.find(&block)
-      end
-      result
+    # Validates a repository exists.
+    # Raises a `LookupError` in the event a repository can't be found.
+    def validate_repo
+      @octokit.repo(owner_repo)
+
+    rescue Octokit::NotFound
+      message = "Unable to find repository #{owner_repo}"
+      message = "#{message}. If the repository is private, try setting GITHUB_OAUTH_TOKEN" unless @oauth_token
+      raise LookupError, message
     end
   end
 end

data/lib/fa-harness-tools/harness_context.rb

@@ -9,7 +9,7 @@ module FaHarnessTools
     end
 
     def new_commit_sha
-      @client.get_commit_sha(@build_no)
+      @new_commit_sha ||= @client.get_commit_sha(@build_no)
     end
   end
 end

data/lib/fa-harness-tools/schedule.rb

@@ -0,0 +1,22 @@
+require 'fugit'
+
+module FaHarnessTools
+  # Creates a schedule which can be used to check if a change
+  # should be deployed.
+  class Schedule
+    def initialize(schedule:)
+      @schedule = schedule
+      @cron_schedule = Fugit.parse(schedule)
+      raise InvalidScheduleError, "'#{schedule}' can not be parsed" unless @cron_schedule
+    end
+
+    def can_run?(time:)
+      return false unless @cron_schedule.day_match?(time)
+      return @cron_schedule.hour_match?(time)
+    end
+
+    def to_s
+      return @schedule
+    end
+  end
+end

data/lib/fa-harness-tools/version.rb

@@ -1,3 +1,3 @@
 module FaHarnessTools
-  VERSION = "1.0.4"
+  VERSION = "1.3.0"
 end

data/lib/fa-harness-tools.rb

@@ -1,11 +1,14 @@
+require "fa-harness-tools/check_logger"
 require "fa-harness-tools/check_branch_protection"
 require "fa-harness-tools/check_forward_deploy"
 require "fa-harness-tools/check_recent_deploy"
 require "fa-harness-tools/check_schedule"
+require "fa-harness-tools/schedule"
 require "fa-harness-tools/github_client"
 require "fa-harness-tools/harness_context"
 require "fa-harness-tools/version"
 
 module FaHarnessTools
   LookupError = Class.new(StandardError)
+  InvalidScheduleError = Class.new(StandardError)
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: fa-harness-tools
 version: !ruby/object:Gem::Version
-  version: 1.0.4
+  version: 1.3.0
 platform: ruby
 authors:
 - FreeAgent
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2019-11-26 00:00:00.000000000 Z
+date: 2021-09-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: octokit
@@ -24,6 +24,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '4.0'
+- !ruby/object:Gem::Dependency
+  name: pastel
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.7'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.7'
 - !ruby/object:Gem::Dependency
   name: tzinfo
   requirement: !ruby/object:Gem::Requirement
@@ -52,6 +66,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: fugit
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
@@ -72,14 +100,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '10.0'
+        version: '13.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '10.0'
+        version: '13.0'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
@@ -121,6 +149,7 @@ executables:
 extensions: []
 extra_rdoc_files: []
 files:
+- ".github/workflows/reviewdog.yml"
 - ".github/workflows/ruby.yml"
 - ".gitignore"
 - ".rspec"
@@ -133,6 +162,10 @@ files:
 - Rakefile
 - bin/console
 - bin/setup
+- examples/create-deployment-tag/README.md
+- examples/create-deployment-tag/create-deployment-tag.sh
+- examples/production-preflight-checks/README.md
+- examples/production-preflight-checks/production-preflight-checks.sh
 - exe/check-branch-protection
 - exe/check-forward-deploy
 - exe/check-recent-deploy
@@ -142,10 +175,12 @@ files:
 - lib/fa-harness-tools.rb
 - lib/fa-harness-tools/check_branch_protection.rb
 - lib/fa-harness-tools/check_forward_deploy.rb
+- lib/fa-harness-tools/check_logger.rb
 - lib/fa-harness-tools/check_recent_deploy.rb
 - lib/fa-harness-tools/check_schedule.rb
 - lib/fa-harness-tools/github_client.rb
 - lib/fa-harness-tools/harness_context.rb
+- lib/fa-harness-tools/schedule.rb
 - lib/fa-harness-tools/version.rb
 homepage: https://github.com/fac/fa-harness-tools
 licenses:
@@ -154,6 +189,7 @@ metadata:
   homepage_uri: https://github.com/fac/fa-harness-tools
   source_code_uri: https://github.com/fac/fa-harness-tools
   changelog_uri: https://github.com/fac/fa-harness-tools/releases
+  allowed_push_host: https://rubygems.org
 post_install_message: 
 rdoc_options: []
 require_paths: