Skip to content

Commit f819803

Browse files
defjosiahbmalehorn
defjosiah
authored and
bmalehorn
committed
Support the context createdAt time for the version (#3)
1 parent 956da70 commit f819803

File tree

5 files changed

+211
-125
lines changed

5 files changed

+211
-125
lines changed

‎README.md

Lines changed: 112 additions & 67 deletions
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@
1010
A Concourse resource for pull requests on Github. Written in Go and based on the [Github V4 (GraphQL) API][graphql-api].
1111
Inspired by [the original][original-resource], with some important differences:
1212

13-
- Github V4: `check` only requires 1 API call per 100th *open* pull request. (See [#costs](#costs) for more information).
13+
- Github V4: `check` only requires 1 API call per 100th _open_ pull request. (See [#costs](#costs) for more information).
1414
- Fetch/merge: `get` will always merge a specific commit from the Pull request into the latest base.
1515
- Metadata: `get` and `put` provides information about which commit (SHA) was used from both the PR and base.
1616
- Webhooks: Does not implement any caching thanks to GraphQL, which means it works well with webhooks.
@@ -20,7 +20,7 @@ Make sure to check out [#migrating](#migrating) to learn more.
2020
## Source Configuration
2121

2222
| Parameter | Required | Example | Description |
23-
|-----------------------------|----------|----------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
23+
| --------------------------- | -------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------- |
2424
| `repository` | Yes | `itsdalmo/test-repository` | The repository to target. |
2525
| `access_token` | Yes | | A Github Access Token with repository access (required for setting status on commits). N.B. If you want github-pr-resource to work with a private repository. Set `repo:full` permissions on the access token you create on GitHub. If it is a public repository, `repo:status` is enough. |
2626
| `v3_endpoint` | No | `https://api.github.com` | Endpoint to use for the V3 Github API (Restful). |
@@ -32,17 +32,18 @@ Make sure to check out [#migrating](#migrating) to learn more.
3232
| `disable_forks` | No | `true` | Disable triggering of the resource if the pull request's fork repository is different to the configured repository. |
3333
| `ignore_drafts` | No | `false` | Disable triggering of the resource if the pull request is in Draft status. |
3434
| `required_review_approvals` | No | `2` | Disable triggering of the resource if the pull request does not have at least `X` approved review(s). |
35-
| `git_crypt_key` | No | `AEdJVENSWVBUS0VZAAAAA...` | Base64 encoded git-crypt key. Setting this will unlock / decrypt the repository with git-crypt. To get the key simply execute `git-crypt export-key -- - | base64` in an encrypted repository. |
35+
| `git_crypt_key` | No | `AEdJVENSWVBUS0VZAAAAA...` | Base64 encoded git-crypt key. Setting this will unlock / decrypt the repository with git-crypt. To get the key simply execute `git-crypt export-key -- - | base64` in an encrypted repository. |
3636
| `base_branch` | No | `master` | Name of a branch. The pipeline will only trigger on pull requests against the specified branch. |
3737
| `labels` | No | `["bug", "enhancement"]` | The labels on the PR. The pipeline will only trigger on pull requests having at least one of the specified labels. |
3838
| `disable_git_lfs` | No | `true` | Disable Git LFS, skipping an attempt to convert pointers of files tracked into their corresponding objects when checked out into a working copy. |
3939
| `states` | No | `["OPEN", "MERGED"]` | The PR states to select (`OPEN`, `MERGED` or `CLOSED`). The pipeline will only trigger on pull requests matching one of the specified states. Default is ["OPEN"]. |
4040

4141
Notes:
42-
- If `v3_endpoint` is set, `v4_endpoint` must also be set (and the other way around).
43-
- Look at the [Concourse Resources documentation](https://concourse-ci.org/resources.html#resource-webhook-token)
44-
for webhook token configuration.
45-
- When using `required_review_approvals`, you may also want to enable GitHub's branch protection rules to [dismiss stale pull request approvals when new commits are pushed](https://help.github.com/en/articles/enabling-required-reviews-for-pull-requests).
42+
43+
- If `v3_endpoint` is set, `v4_endpoint` must also be set (and the other way around).
44+
- Look at the [Concourse Resources documentation](https://concourse-ci.org/resources.html#resource-webhook-token)
45+
for webhook token configuration.
46+
- When using `required_review_approvals`, you may also want to enable GitHub's branch protection rules to [dismiss stale pull request approvals when new commits are pushed](https://help.github.com/en/articles/enabling-required-reviews-for-pull-requests).
4647

4748
## Behaviour
4849

@@ -62,25 +63,26 @@ If several commits are pushed to a given PR at the same time, the last commit wi
6263
This resource does not implement any caching, so it should work well with webhooks (should be subscribed to `push` and `pull_request` events).
6364
One thing to keep in mind however, is that pull requests that are opened from a fork and commits to said fork will not
6465
generate notifications over the webhook. So if you have a repository with little traffic and expect pull requests from forks,
65-
you'll need to discover those versions with `check_every: 1m` for instance. `check` in this resource is not a costly operation,
66-
so normally you should not have to worry about the rate limit.
66+
you'll need to discover those versions with `check_every: 1m` for instance. `check` in this resource is not a costly operation,
67+
so normally you should not have to worry about the rate limit.
6768

6869
#### `get`
6970

7071
| Parameter | Required | Example | Description |
71-
|----------------------|----------|----------|------------------------------------------------------------------------------------|
72+
| -------------------- | -------- | -------- | ---------------------------------------------------------------------------------- |
7273
| `skip_download` | No | `true` | Use with `get_params` in a `put` step to do nothing on the implicit get. |
7374
| `integration_tool` | No | `rebase` | The integration tool to use, `merge`, `rebase` or `checkout`. Defaults to `merge`. |
7475
| `git_depth` | No | `1` | Shallow clone the repository using the `--depth` Git option |
75-
| `submodules` | No | `true` | Recursively clone git submodules. Defaults to false. |
76+
| `submodules` | No | `true` | Recursively clone git submodules. Defaults to false. |
7677
| `list_changed_files` | No | `true` | Generate a list of changed files and save alongside metadata |
77-
| `fetch_tags` | No | `true` | Fetch tags from remote repository |
78+
| `fetch_tags` | No | `true` | Fetch tags from remote repository |
7879

7980
Clones the base (e.g. `master` branch) at the latest commit, and merges the pull request at the specified commit
8081
into master. This ensures that we are both testing and setting status on the exact commit that was requested in
8182
input. Because the base of the PR is not locked to a specific commit in versions emitted from `check`, a fresh
82-
`get` will always use the latest commit in master and *report the SHA of said commit in the metadata*. Both the
83+
`get` will always use the latest commit in master and _report the SHA of said commit in the metadata_. Both the
8384
requested version and the metadata emitted by `get` are available to your tasks as JSON:
85+
8486
- `.git/resource/version.json`
8587
- `.git/resource/metadata.json`
8688
- `.git/resource/changed_files` (if enabled by `list_changed_files`)
@@ -98,23 +100,22 @@ Example here:
98100
put: update-status <-- Use an alias for the pull-request resource
99101
resource: pull-request
100102
params:
101-
path: pull-request
102-
status: pending
103-
get_params: {skip_download: true}
103+
path: pull-request
104+
status: pending
105+
get_params: { skip_download: true }
104106
```
105107
106108
git-crypt encrypted repositories will automatically be decrypted when the `git_crypt_key` is set in the source configuration.
107109

108110
Note that, should you retrigger a build in the hopes of testing the last commit to a PR against a newer version of
109111
the base, Concourse will reuse the volume (i.e. not trigger a new `get`) if it still exists, which can produce
110-
unexpected results (#5). As such, re-testing a PR against a newer version of the base is best done by *pushing an
111-
empty commit to the PR*.
112-
112+
unexpected results (#5). As such, re-testing a PR against a newer version of the base is best done by _pushing an
113+
empty commit to the PR_.
113114

114115
#### `put`
115116

116117
| Parameter | Required | Example | Description |
117-
|----------------------------|----------|--------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------|
118+
| -------------------------- | -------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
118119
| `path` | Yes | `pull-request` | The name given to the resource in a GET step. |
119120
| `status` | No | `SUCCESS` | Set a status on a commit. One of `SUCCESS`, `PENDING`, `FAILURE` and `ERROR`. |
120121
| `base_context` | No | `concourse-ci` | Base context (prefix) used for the status context. Defaults to `concourse-ci`. |
@@ -133,83 +134,87 @@ See https://concourse-ci.org/implementing-resource-types.html#resource-metadata
133134

134135
```yaml
135136
resource_types:
136-
- name: pull-request
137-
type: docker-image
138-
source:
139-
repository: teliaoss/github-pr-resource
137+
- name: pull-request
138+
type: docker-image
139+
source:
140+
repository: teliaoss/github-pr-resource
140141
141142
resources:
142-
- name: pull-request
143-
type: pull-request
144-
check_every: 24h
145-
webhook_token: ((webhook-token))
146-
source:
147-
repository: itsdalmo/test-repository
148-
access_token: ((github-access-token))
143+
- name: pull-request
144+
type: pull-request
145+
check_every: 24h
146+
webhook_token: ((webhook-token))
147+
source:
148+
repository: itsdalmo/test-repository
149+
access_token: ((github-access-token))
149150
150151
jobs:
151-
- name: test
152-
plan:
153-
- get: pull-request
154-
trigger: true
155-
version: every
156-
- put: pull-request
157-
params:
158-
path: pull-request
159-
status: pending
160-
- task: unit-test
161-
config:
162-
platform: linux
163-
image_resource:
164-
type: docker-image
165-
source: {repository: alpine/git, tag: "latest"}
166-
inputs:
167-
- name: pull-request
168-
run:
169-
path: /bin/sh
170-
args:
171-
- -xce
172-
- |
173-
cd pull-request
174-
git log --graph --all --color --pretty=format:"%x1b[31m%h%x09%x1b[32m%d%x1b[0m%x20%s" > log.txt
175-
cat log.txt
176-
on_failure:
177-
put: pull-request
178-
params:
179-
path: pull-request
180-
status: failure
181-
- put: pull-request
182-
params:
183-
path: pull-request
184-
status: success
152+
- name: test
153+
plan:
154+
- get: pull-request
155+
trigger: true
156+
version: every
157+
- put: pull-request
158+
params:
159+
path: pull-request
160+
status: pending
161+
- task: unit-test
162+
config:
163+
platform: linux
164+
image_resource:
165+
type: docker-image
166+
source: { repository: alpine/git, tag: "latest" }
167+
inputs:
168+
- name: pull-request
169+
run:
170+
path: /bin/sh
171+
args:
172+
- -xce
173+
- |
174+
cd pull-request
175+
git log --graph --all --color --pretty=format:"%x1b[31m%h%x09%x1b[32m%d%x1b[0m%x20%s" > log.txt
176+
cat log.txt
177+
on_failure:
178+
put: pull-request
179+
params:
180+
path: pull-request
181+
status: failure
182+
- put: pull-request
183+
params:
184+
path: pull-request
185+
status: success
185186
```
186187

187188
## Costs
188189

189190
The Github API(s) have a rate limit of 5000 requests per hour (per user). For the V3 API this essentially
190-
translates to 5000 requests, whereas for the V4 API (GraphQL) the calculation is more involved:
191+
translates to 5000 requests, whereas for the V4 API (GraphQL) the calculation is more involved:
191192
https://developer.github.com/v4/guides/resource-limitations/#calculating-a-rate-limit-score-before-running-the-call
192193

193194
Ref the above, here are some examples of running `check` against large repositories and the cost of doing so:
195+
194196
- [concourse/concourse](https://github.com/concourse/concourse): 51 open pull requests at the time of testing. Cost 2.
195197
- [torvalds/linux](https://github.com/torvalds/linux): 305 open pull requests. Cost 8.
196198
- [kubernetes/kubernetes](https://github.com/kubernetes/kubernetes): 1072 open pull requests. Cost: 22.
197199

198200
For the other two operations the costing is a bit easier:
201+
199202
- `get`: Fixed cost of 1. Fetches the pull request at the given commit.
200203
- `put`: Uses the V3 API and has a min cost of 1, +1 for each of `status`, `comment` and `comment_file` etc.
201204

202205
## Migrating
203206

204-
If you are coming from [jtarchie/github-pullrequest-resource][original-resource], its important to know that this resource is inspired by *but not a drop-in replacement for* the original. Here are some important differences:
207+
If you are coming from [jtarchie/github-pullrequest-resource][original-resource], its important to know that this resource is inspired by _but not a drop-in replacement for_ the original. Here are some important differences:
205208

206209
#### New parameters:
210+
207211
- `source`:
208212
- `v4_endpoint` (see description above)
209213
- `put`:
210214
- `comment` (see description above)
211215

212216
#### Parameters that have been renamed:
217+
213218
- `source`:
214219
- `repo` -> `repository`
215220
- `ci_skip` -> `disable_ci_skip` (the logic has been inverted and its `true` by default)
@@ -223,6 +228,7 @@ If you are coming from [jtarchie/github-pullrequest-resource][original-resource]
223228
- `comment` -> `comment_file` (because we added `comment`)
224229

225230
#### Parameters that are no longer needed:
231+
226232
- `src`:
227233
- `uri`: We fetch the URI directly from the Github API instead.
228234
- `private_key`: We clone over HTTPS using the access token for authentication.
@@ -233,6 +239,7 @@ If you are coming from [jtarchie/github-pullrequest-resource][original-resource]
233239
- `fetch_merge`: We are opinionated and always do a fetch_merge.
234240

235241
#### Parameters that did not make it:
242+
236243
- `src`:
237244
- `authorship_restriction`
238245
- `label`
@@ -246,3 +253,41 @@ If you are coming from [jtarchie/github-pullrequest-resource][original-resource]
246253
Note that if you are migrating from the original resource on a Concourse version prior to `v5.0.0`, you might
247254
see an error `failed to unmarshal request: json: unknown field "ref"`. The solution is to rename the resource
248255
so that the history is wiped. See [#64](https://github.com/telia-oss/github-pr-resource/issues/64) for details.
256+
257+
## Debugging
258+
259+
The following query is useful for debugging with the github
260+
graphql explorer
261+
262+
```graphql
263+
# Type queries into this side of the screen, and you will
264+
# see intelligent typeaheads aware of the current GraphQL type schema,
265+
# live syntax, and validation errors highlighted within the text.
266+
267+
# We'll get you started with a simple query showing your username!
268+
query {
269+
repository(name: "code", owner: "opendoor-labs") {
270+
pullRequests(first: 100) {
271+
edges {
272+
node {
273+
commits(last: 1) {
274+
edges {
275+
node {
276+
commit {
277+
status {
278+
contexts {
279+
context
280+
createdAt
281+
state
282+
}
283+
}
284+
}
285+
}
286+
}
287+
}
288+
}
289+
}
290+
}
291+
}
292+
}
293+
```

0 commit comments

Comments
 (0)