The latest release of the GitHub Branch Source Plugin added support for github commit status notifications. I was seriously happy about this, because I thought this would allow me to remove generic

step([$class: 'GitHubSetCommitStatusBuilder'])

and

step([$class: 'GitHubCommitNotifier', resultOnFailure: 'FAILURE'])

steps from my workflow scripts.

Unfortunately, I was seriously let down by the new functionality, and I found major issues with how it interacts with the workflow plugin.

No support for multiple `node` / `checkout` combinations

My Workflow scripts reserve different nodes and checkout the same code on
these. This might happen in parallel, or in sequence. After the steps on the
first node finish, the build gets marked as successful, even if later steps
are still pending. If a later step fails, a previously successful build will
suddenly get marked as successful. I haven't tested with parallel builds yet,
but I believe that might cause even weirder issues.

No flexibility

My workflow jobs sometimes consist of multiple different steps,
like Validation, Build, Test, Deployments. With the generic steps mentioned
above, I was able to be flexible on when the "final" commit status was set.
E.g for one job, I want the commit status to be set after the code was build
and tested, irrelevant of the deployment step.

I thus propose an alternative solution:

Instead of making the sending of the commit status automatic, custom workflow
steps should be added to the `github` plugin. These steps should be flexible
enough to allow users to use them in even the most complex workflow scripts,
while also having sensible defaults to make them easy to use.

withGitHubCommitStatus

This step should take a block and update the commit status on GitHub. By default,
it should use the GitHub URL, Commit ID and other required information from
the main git source for the job.

This step could take a bunch of optional parameters:

• sha: Commit ID to set the status for. (Default: Taken from build)
• repo: Repository name. (Default: Taken from build)
• owner: Owner name (user or organization). (Default: Taken from build)
• context: Context to be used for the status. (Default: "default" or "continuous-integration/jenkins")
• targetUrl: URL to be linked to in the GitHub UI. (Default: Build URL)

Based on whether the contained block passes or not, the status on GitHub should be set
accordingly.

setGitHubCommitStatus

This is basically a non-block version the same as withGitHubCommitStatus.

It should take the same parameters as withGitHubCommitStatus, plus the following:

• state: pending, success, error, or failure.
• description: A custom description.

Here's same example Workflow scripts that show how this could be used:

#!/usr/bin/env groovy

stage name: 'build'

parallel lint: {
  withGitHubCommitStatus context: "continuous-integration/jenkins/lint" {
    node {
      checkout scm

      sh('script/setup')
      sh('script/lint')
    }
  }
}, test: {
  withGitHubCommitStatus context: "continuous-integration/jenkins/test" {
    node {
      checkout scm

      sh('script/setup')
      sh('script/test')
    }
  }
}

// Prepare a deployment
stage name: 'prepare-deployment'
node {
  checkout scm

  sh('script/setup')
  sh('script/prepare-deploy')
}

// Run deployments
if (currentBuild.result != 'FAILURE' && env.BRANCH_NAME == 'master') {
  input 'Trigger Deployment?'

  stage name: 'deployment', concurrency: 1

  node {
    checkout scm

    sh('script/setup')
    sh('script/deploy')
  }
}