From 9096a976d72b92a632d396b2fa4c8b9cba99af75 Mon Sep 17 00:00:00 2001 From: Torben Neufeldt Date: Sun, 21 Jun 2020 01:40:10 +0200 Subject: [PATCH] Add documentation --- README.md | 26 ++++++++++++++++++++++++-- 1 file changed, 24 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index d46077ff..026b120e 100644 --- a/README.md +++ b/README.md @@ -17,12 +17,34 @@ Inspired by [the original][original-resource], with some important differences: Make sure to check out [#migrating](#migrating) to learn more. -## Source Configuration +## Configuration + +### Authentication +You can either use a personal access token or let the resource run as a [Github App](https://developer.github.com/apps/). + +#### Personal access token +Please set the `access_token`. +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. + +#### Github App +This is useful when you are part of an organisation and do not want to share your personal access token with everyone else having access to your Secrets Manager. +Please provide `app_id`, `private_key`, `installation_id`. + +We need the following permissions: +- Contents - Read-only => required +- Pull-requests - Read-only => required +- Pull-requests - Read & write => To write/delete comments on pull requests +- Commit statuses - Read & write => To set a commit status + +### Source | Parameter | Required | Example | Description | |-----------------------------|----------|----------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `repository` | Yes | `itsdalmo/test-repository` | The repository to target. | -| `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. | +| `access_token` | Auth | | A Github Access Token with repository access (required for setting status on commits). | +| `app_id` | Auth | `69592` | The Github App app id you can find on top of the overview page. | +| `private_key` | Auth | `-----BEGIN RSA PRIVATE KEY....` | The private key of your Github App as described [here](https://developer.github.com/apps/building-github-apps/authenticating-with-github-apps/). | +| `installation_id` | Auth | `9912873` | On the overview page of your app you can find `Install App` on the left. After installing it you can click on a specific installation and retrieve the numeric installation id from the url. | | `v3_endpoint` | No | `https://api.github.com` | Endpoint to use for the V3 Github API (Restful). | | `v4_endpoint` | No | `https://api.github.com/graphql` | Endpoint to use for the V4 Github API (Graphql). | | `paths` | No | `["terraform/*/*.tf"]` | Only produce new versions if the PR includes changes to files that match one or more glob patterns or prefixes. |