pixelairio/github-resource repository overview

⁠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
    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, changing check statuses or posting comments.

⁠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.

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:

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:

The get checks out a commit from the Pull Request and locally merges them 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: