dpb587 / github-status-resource

A Concourse resource to interact with the GitHub Status type

github-status-resource

A Concourse resource to interact with the GitHub Status type.

Configuration

• repository - the owner and repository name, slash delimited (e.g. dpb587/github-status-resource)
• access_token - GitHub API access token from a user with write access to the repository (minimum token scope of repo:status)
• branch - the branch currently being monitored (default: master)
• context - a label to differentiate this status from the status of other systems (default: default)
• endpoint - GitHub API endpoint (default: https://api.github.com)
• skip_ssl_verification - Disable certificate validation for GitHub API calls (default: false)

Behavior

check

Triggers when the status of the branch for the configured context has been updated.

in

Lookup the state of a status.

• /commit - the commit reference of the status
• /description - a short description of the status
• /state - the state of the status
• /target_url - the target URL associated with the status
• /updated_at - when the status was last updated

out

Update the status of a commit. Optionally include a description and target URL which will be referenced from GitHub.

Parameters:

• commit - specific commit sha affiliated with the status. Value must be either: path to an input git directory whose detached HEAD will be used; or path to an input file whose contents is the sha
• state - the state of the status. Must be one of pending, success, error, or failure
• description - a short description of the status
• description_path - path to an input file whose data is the value of description
• target_url - the target URL to associate with the status (default: concourse build link)

Example

A typical use case is to update the status of a commit as it traverses your pipeline. The following example marks the commit as pending before unit tests start. Once unit tests finish, the status is updated to either success or failure depending on how the task completes.

---
jobs:
  - name: "unit-tests"
    plan:
      - get: "repo"
        trigger: true
      - put: "repo-status"                               # +
        params: { state: "pending", commit: "repo" }     # +
      - task: "unit-tests"
        file: "repo/ci/unit-tests/task.yml"
        on_failure:
          - put: "repo-status"                           # +
            params: { state: "failure", commit: "repo" } # +
      - put: "repo-status"                               # +
        params: { state: "success", commit: "repo" }     # +
resources:
  - name: "repo"
    type: "git"
    source:
      uri: {{repo_uri}}
      branch: {{repo_branch}}
  - name: "repo-status"                                  # +
    type: "github-status"                                # +
    source:                                              # +
      repository: {{repo_github_path}}                   # +
      access_token: {{repo_github_token}}                # +

When testing pull requests, use the PR ref as the branch. For example, if testing PR #12345 to your repository, your resource might look like...

name: "pr-status"
type: "github-status"
source:
  repository: {{repo_github_path}}
  access_token: {{repo_github_token}}
  branch: "pull/12345/head"           # +

For another pipeline example, see ci/pipelines/main.yml which operates against this repository.

Installation

This resource is not included with the standard Concourse release. Use one of the following methods to make this resource available to your pipelines.

Deployment-wide

To install on all Concourse workers, update your deployment manifest properties to include a new groundcrew.resource_types entry...

properties:
  groundcrew:
    additional_resource_types:
      - image: "docker:///dpb587/github-status-resource#master" # +
        type: "github-status"                                   # +

Pipeline-specific

To use on a single pipeline, update your pipeline to include a new resource_types entry...

resource_types:
  - name: "github-status"                         # +
    type: "docker-image"                          # +
    source:                                       # +
      repository: "dpb587/github-status-resource" # +
      tag: "master"                               # +

References

• Resources (concourse.ci)
• Statuses | GitHub Developer Guide (developer.github.com)
• Enabling required status checks (help.github.com)
• Personal Access Tokens (github.com)

License

MIT License

github-status-resource's Issues

Permissions errors are a bit opaque

I got stumped by this:

FATAL: Status not found on [git sha]

Superficially this looks like #3, but it wasn't. The problem was that the relevant bot didn't have write access to the relevant repository.

It would be good if

• the docs outlined the starting position of having write access, as well as the existing note on token scope
• the code sniffed out permissions errors and told you about them.

Support for Github actions

I have one short question - are there any plans to add support for GitHub actions?

Warn or error when using unexpected status state

Sounds like using a GitHub-unexpected state results in very confusing errors. Should perform some validation when putting, or handle the later [error?] responses more gracefully.

#3 (comment)

/cc @jchesterpivotal

Allow to monitor all branches or all PRs

It would be very useful to run this resource to build status reports for all PRs opened against a repository, but as far as I can see, this is not possible, since we are restricted to monitoring a specific branch? (teliaoss/github-pr-resource provides this functionality, but I would prefer not to use two different resources to interact with statuses per commit or per PR).

failed to fetch digest: 404 Not Found

Hey thank you for repo. I am trying to use the github status

i get the following error

resource script '/opt/resource/check []' failed: exit status 1
stderr:
failed to fetch digest: 404 Not Found

my config

resource_types    :
  - name          : "github-status"
    type          : docker-image
    source        : 
      repository  : dpb587/github-status-resource
      tags        : master
resources         :
  - name          : status
    type          : github-status
    source        :
      repository  : myrepo/myproj
      access_token: {{github_token}}
jobs:
  - name   : PR-initial-tests
    plan   :
#       ..... other stuf
      - put: status
        params: {commit: automation-artifcat/commitish, state: success, description: Drafting release }

Any pointers what i am doing wrong ?

Allow source_context to evaluate build env vars

This would allow different jobs within the pipeline to post to separate statuses and support simple copy/paste between pipelines.

Status not found on commit

Sometimes, after putting the new status, the implicit get will fail because it can't find the status on the commit. I think this could be resolved by having the put wait for a bit and check that the status actually appears. What's your opinion on this?

jq error

Using the example config I'm getting the following error:

jq: error (at <stdin>:4): Cannot iterate over null (null)

I also don't want to write my own resource. Could you please verify that error or tell me if I'm doing something wrong.

Default context ought to use Concourse-provided variables

For example, something like ci/$BUILD_PIPELINE_NAME/$BUILD_JOB_NAME.

This would make it easier to reuse the resource across multiple jobs, while retaining the distinction of builds via context in Github.