Concourse Github Issue Resource

A concourse-ci resource for interacting with Github Issues.

This repository and project is based on the work performed for MITODL, and now serves as an upstream for the project hosted within that organization. Accordingly it maintains the BSD-3 license with copyright notice.

Behavior

source: designates the Github repository, issue number, and personal access token

parameters

• pat: required/optional The personal access token for authentication and authorization. If anonymous read and write for Issues is permitted, then this is optional for the check and out steps. Otherwise it is required for private repos, or any other situation where anonymous read and write for Issues is not authorized.

• owner: required The owner of the target repository expressed as either a user or organization.

• repo: required The Github repository with the issue tracker in which to read and/or write issues.

• skip_check: optional A boolean that signifies whether to skip the check step or not. This is primarily useful for situations where it is known that a specified issue does not exist, and instead must be created during out.

• number: optional The issue number to read during the check step for triggering Concourse pipelines based on the issue state, or for updating during the out step (future feature). If this is omitted then instead a list operation with filters (i.e. "search") occurs to determine the issue.

The following parameters are for filtering from a list of issues to one issue (i.e. "search") during the check step, and therefore their values are ignored when an input value is specified for the number parameter.

• state: optional (value currently ignored) The current state of the searched issue. This can be either Open, Closed, or All.

• milestone: optional The numeric ID of the milestone associated with the searched issue.

• assignee: optional The user name of the assignee for the searched issue.

• labels: optional (value currently ignored) The list of labels for the searched issue.

version: designates the Github issue state

parameters

• version: optional The state of the issue specified in the source expressed as the enum Closed or Open converted to a string. This is an output only and is ignored as an input parameter.

version:
  state: <issue state>

check: returns size two list for Closed Github issues and size one list for Open Github issues

The check step determines the state of the specified Github issue. If the state is Closed then the returned list of versions is size two. If the state is Open then the returned list of versions is size one. This is specifically to trigger pipelines based on the issue state (Closed triggers and Open does not trigger) because it simulates a delta of versions for Closed and not Open. The actual returns are the following:

Closed:

[{"state":"Open"},{"state":"Closed"}]

Open:

[{"state":"Open"}]

in: currently unused

This ignores any inputs and quickly dummies outputs, and therefore is primarily useful for executing an efficient check step with minimal overhead.

out: creates a Github issue

The out step creates a Github issue (in the future will also update an issue) according to the input parameters below. The number of the created Github issue is written to a file at /opt/resource/issue_number.txt so that it can be re-used later in the build (especially for a subsequent check step to trigger Concourse steps based on the status of the Github issue created during this step).

The metadata output from this step contains the number, labels, assignees, and milestone for the issue.

• title: required The title of the written Github issue.

• body: optional The body of the written Github issue.

• labels: optional (value currently ignored) The list of labels for the written Github issue.

• assignees: optional The list of assignees for the written Github issue.

• milestone: optional The milestone numeric ID to associate with the written Github issue.

• state: optional (value currently ignored) The desired state of the updated issue (future feature). This can be either Open or Closed.

Example

resource_types:
- name: github_issue
  type: docker-image
  source:
    repository: mitodl/concourse-github-issue-resource
    tag: latest

resources:
- name: github-issue
  type: github-issue
  source:
    pat: abcdefg12345!
    owner: mitodl
    repo: ol-infrastructure
    skip_check: true
- name: github-issue-check
  type: github-issue
  source:
    owner: mitodl
    repo: ol-infrastructure
    number: 1

jobs:
- name: do something
  plan:
  - get: my-code
  - task: something cool
    file: foo.yml
    on_failure:
      put: github-issue
      params:
        title: concourse failed
        body: go fix it
        assignees:
        - my_user
        - your_user
  - get: githhub-issue-check

Contributing

Code should pass all unit and acceptance tests. New features should involve new unit tests.

Please consult the GitHub Project for the current development roadmap.