GitHub Resource

A Concourse resource for working with GitHub. This resource can be configured to track and update different resources within GitHub. It's multiple Concourse resources bundled into one container image.

Use it in your pipeline:

resource_types:
- name: github
  type: registry-image
  source:
    repository: docker.io/pixelairio/github-resource
    tag: latest

resources:
- name: prs
  type: github
  source:
    kind: prs # One of: prs, pr, commits-from-prs
    access_token: gh_pat...
    repository: owner/repo
    # See below for config options, depending on which kind is selected

The kind, access_token, repository fields are always required. The following sections explain each field's usage.

kind - Picking the Resource to Track

The following kind's are supported:

• prs - Returns a list of pull requests.
• pr - Work with a single Pull Request, updating check status.
• commits-from-prs - Lists the latest commits from matching PRs, updating their check status.

access_token - Configuring Authentication

Authentication is optional if you're accessing public repositories, but you'll likely want to configure it to avoid rate-limits. Create a Personal Access token (classic or fine-grained work).

You can also configure the the resource to use a token from a GitHub or OAuth app. See the GitHub docs for details: https://docs.github.com/en/graphql/guides/forming-calls-with-graphql#authenticating-with-graphql

repository

This is the repository to target in the format of OWNER/REPO. For example, the repository https://github.com/example/my-app would become repository: example/my-app.

Custom Endpoints

The endpoints used can be configured by setting the following:

• graphql_endpoint - Defaults to the GraphQL endpoint https://api.github.com/graphql
• rest_endpoint - Defaults to the REST endpoint https://api.github.com
• host_endpoint - Defaults to https://github.com, where repositories are hosted
• skip_ssl_verification - Skips SSL verification

We try to mostly use the GraphQL API because you're less likely to hit API rate limits compared to the REST API.

The following table outlines the required permissions for each kind.

kind	Classic Token	Fine-grained Token
prs	repo:public_repo	Public repository access or Repository permission "Read access to metadata"
pr	repo:status	Repository permission "Commit statuses" (Write)

---

The next sections describe how to configure each kind of this resource type.

---

kind: prs

Returns a list of Pull Requests against a given repository. Can filter by the PR's status, labels, draft status, and target branch the PR wants to merge into.

source has the following additional fields:

Field Name	Description
states(Optional) Default Value: ["OPEN"]	A list of PR statuses to filter PR's by. Allowed values are: OPEN, CLOSED, MERGED.
labels(Optional)	A list of label(s) to filter PR's by. A PR containing any of the labels will be matched.
target_branch(Optional)	Only track PRs that merge into the specified branch.
exclude_drafts(Optional) Default Value: false	Exclude PRs that are currently drafts.

Only the get step is supported. The put step is a no-op and will error if you try to use it. The get step will write the list of PR's to a file, prs.json, as a JSON array of the PR numbers and other information. The numbers will be saved as strings, not integers.

Example of prs.json:

[
  {
    "number": "1234",
    "url": "http://...",
    "target_branch": "main"
  }
]

In the case when there are no matching PRs, a special none version will be generated. The get step will populate prs.json with an empty array that can be passed to the across step.

kind: pr

Allows you to interact with a single Pull Request. Will track commits pushed to the pull request and allow you to update the status checks of the PR and leave comments.

source has the following additional fields:

Field Name	Description
number(Required)	The PR number that the resource will interact with.
merge_strategy(Optional) Defaults to merge	Dictates how the PR will be checked out. Can be one of: merge - Will checkout the branch the PR wants to merge into and locally merge the PR into that branch. rebase - Will checkout the branch the PR wants to merge into and locally rebase the PR on the latest commit of that branch. checkout - Only checks out the PR branch.
depth(Optional)	Shallow clone the repository using git's --depth flag
submodules(Optional)	Set to true if you want submodules to be cloned.
fetch_tags(Optional)	Set to true if you want tags to be fetched.
disable_git_lfs(Optional)	Set to true to not download LFS files.

The get checks out a commit from the Pull Request and locally merges it into the target branch (unless merge_strategy: checkout is used).

The put step can set the status on a commit of the Pull Request. One instance of the resource can be used to set multiple statuses on the PR by calling put with different params.

The put step has the following params:

Field Name	Description
ref(Required)	The commit SHA that the PR check will be matched with on GitHub.
name(Required)	The name of the check that will be displayed in the list of PR checks for the PR (e.g. `unit-tests`, `integration`). You can use Build Metadata in the name like $BUILD_JOB_NAME.
status(Required)	One of: pending, success, error, or failure
description(Optional)	Description that will appear alongside the name of the PR check.

kind: commits-from-prs

Tracks the latest commits from all matching PR's in a given repository. Each version emitted represents one commit. This is a combination of the previous two kinds. It is useful when you don't want each PR getting its own pipeline.

source has the following additional fields:

Field Name	Description
states(Optional) Default Value: ["OPEN"]	A list of PR statuses to filter PR's by. Allowed values are: OPEN, CLOSED, MERGED.
labels(Optional)	A list of label(s) to filter PR's by. A PR containing any of the labels will be matched.
target_branch(Optional)	Only track PRs that merge into the specified branch.
exclude_drafts(Optional) Default Value: false	Exclude PRs that are currently drafts.
merge_strategy(Optional) Defaults to merge	Dictates how the PR will be checked out. Can be one of: merge - Will checkout the branch the PR wants to merge into and locally merge the PR into that branch. rebase - Will checkout the branch the PR wants to merge into and locally rebase the PR on the latest commit of that branch. checkout - Only checks out the PR branch.
depth(Optional)	Shallow clone the repository using git's --depth flag
submodules(Optional)	Set to true if you want submodules to be cloned.
fetch_tags(Optional)	Set to true if you want tags to be fetched.
disable_git_lfs(Optional)	Set to true to not download LFS files.

The get checks out the latest commit from a Pull Request and locally merges it into the target branch (unless merge_strategy: checkout is used).

The put step can set the status on a commit of the Pull Request. One instance of the resource can be used to set multiple statuses on the PR by calling put with different params.

The put step has the following params:

Field Name	Description
ref(Required)	The commit SHA that the PR check will be matched with on GitHub.
pr(Required)	The PR number that the PR check will be matched with on GitHub.
commit_date(Required)	The commit date, returned by the previously run get step.
name(Required)	The name of the check that will be displayed in the list of PR checks for the PR (e.g. `unit-tests`, `integration`). You can use Build Metadata in the name like $BUILD_JOB_NAME.
status(Required)	One of: pending, success, error, or failure
description(Optional)	Description that will appear alongside the name of the PR check.

Typical usage would look like this in your job:

jobs:
- name: test
  plan:
    - do:
      - get: pr-commit
        version: every
      - put: pr-commit
        no_get: true
        params:
          ref: ((.:pr-commit.ref))
          pr: ((.:pr-commit.pr))
          commit_date: ((.:pr-commit.commit_date))
          name: tests
          status: pending
    - # other steps happen here
  on_failure:
    put: pr-commit
    no_get: true
    params:
      ref: ((.:pr-commit.ref))
      pr: ((.:pr-commit.pr))
      commit_date: ((.:pr-commit.commit_date))
      name: tests
      status: failure
  on_success:
    put: pr-commit
    no_get: true
    params:
      ref: ((.:pr-commit.ref))
      pr: ((.:pr-commit.pr))
      commit_date: ((.:pr-commit.commit_date))
      name: tests
      status: success