From 6cafb5ef1a1ad0eaa9b62adc4d711746ad287b6a Mon Sep 17 00:00:00 2001 From: pat-s Date: Mon, 18 Sep 2023 21:30:55 +0200 Subject: [PATCH 1/3] update GH app installation --- .../30-administration/11-forges/20-github.md | 86 +++++++++---------- 1 file changed, 43 insertions(+), 43 deletions(-) diff --git a/docs/docs/30-administration/11-forges/20-github.md b/docs/docs/30-administration/11-forges/20-github.md index 5d21a8a9f8..08adc9ec7d 100644 --- a/docs/docs/30-administration/11-forges/20-github.md +++ b/docs/docs/30-administration/11-forges/20-github.md @@ -1,72 +1,72 @@ # GitHub -Woodpecker comes with built-in support for GitHub and GitHub Enterprise. To enable GitHub you should configure the Woodpecker server using the following environment variables: +Woodpecker comes with built-in support for GitHub and GitHub Enterprise. +To use Woodpecker with GitHub the following environment variables should be set for the server component: ```diff -# docker-compose.yml -version: '3' - -services: - woodpecker-server: - [...] - environment: - - [...] -+ - WOODPECKER_GITHUB=true + - WOODPECKER_GITHUB_CLIENT=${WOODPECKER_GITHUB_CLIENT} + - WOODPECKER_GITHUB_SECRET=${WOODPECKER_GITHUB_SECRET} - - woodpecker-agent: - [...] ``` -## Registration +You will get these values from GitHub when you register your application. +To do so, go to Settings -> Developer Settings -> GitHub Apps -> New GitHub App. -Register your application with GitHub to create your client id and secret. It is very important that the authorization callback URL matches your http(s) scheme and hostname exactly with `:///authorize` as the path. +## App Settings -Please use this screenshot for reference: +- Name: An arbitrary name for your App +- Homepage URL: The URL of your Woodpecker instance +- Callback URL: `https:///authorize` +- Leave "Request user authorization (OAuth) during installation" and "Enable Device Flow" unchecked +- Leave "Webhook" and "Post Installation" fields empty +- (optional) Upload the Woodpecker Logo: https://avatars.githubusercontent.com/u/84780935?s=200&v=4 -![github oauth setup](github_oauth.png) +## App Permissions -## Configuration +The app must be granted the following permissions: -This is a full list of configuration options. Please note that many of these options use default configuration values that should work for the majority of installations. +Repository: + +- Commit statuses: Read & write +- Contents: Read & write +- Deployments: Read & write +- Metadata: Read-only +- Pull requests: Read & write +- Secrets: Read & write +- Webhooks: Read & write -### `WOODPECKER_GITHUB` -> Default: `false` +Organization: -Enables the GitHub driver. +- Members: Read-only -### `WOODPECKER_GITHUB_URL` -> Default: `https://github.com` +Account: -Configures the GitHub server address. +- Email addresses: Read-only -### `WOODPECKER_GITHUB_CLIENT` -> Default: empty +## Client Secret -Configures the GitHub OAuth client id. This is used to authorize access. +After your App has been created, you can generate a client secret. +Use this one for the `WOODPECKER_GITHUB_SECRET` environment variable. -### `WOODPECKER_GITHUB_CLIENT_FILE` -> Default: empty +## Installing the app -Read the value for `WOODPECKER_GITHUB_CLIENT` from the specified filepath +In the app settings, click on "Install App" and give the app permissions to the repositories you want to use with Woodpecker. + +## All GitHub Configuration Options + +This is a full list of configuration options. Please note that many of these options use default configuration values that should work for the majority of installations. -### `WOODPECKER_GITHUB_SECRET` -> Default: empty +- `WOODPECKER_GITHUB` - Enables the GitHub driver (Default: `false`) -Configures the GitHub OAuth client secret. This is used to authorize access. +- `WOODPECKER_GITHUB_URL` - Configures the GitHub server address (Default: `https://github.com`) -### `WOODPECKER_GITHUB_SECRET_FILE` -> Default: empty +- `WOODPECKER_GITHUB_CLIENT` - Configures the GitHub OAuth client id to authorize access (Default: empty) -Read the value for `WOODPECKER_GITHUB_SECRET` from the specified filepath +- `WOODPECKER_GITHUB_CLIENT_FILE` - Read the value for `WOODPECKER_GITHUB_CLIENT` from the specified filepath (Default: empty) -### `WOODPECKER_GITHUB_MERGE_REF` -> Default: `true` +- `WOODPECKER_GITHUB_SECRET` - Configures the GitHub OAuth client secret. This is used to authorize access. (Default: empty) -TODO +- `WOODPECKER_GITHUB_SECRET_FILE` - Read the value for `WOODPECKER_GITHUB_SECRET` from the specified filepath 9Default: empty) -### `WOODPECKER_GITHUB_SKIP_VERIFY` -> Default: `false` + `WOODPECKER_GITHUB_MERGE_REF` - (Default: `true`) -Configure if SSL verification should be skipped. +- `WOODPECKER_GITHUB_SKIP_VERIFY` - Configure if SSL verification should be skipped (Default: `false`) From 7d5e4b9dd3dd40d41472cb140c82031784c86771 Mon Sep 17 00:00:00 2001 From: pat-s Date: Mon, 18 Sep 2023 21:38:01 +0200 Subject: [PATCH 2/3] refine --- docs/docs/30-administration/11-forges/20-github.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/docs/docs/30-administration/11-forges/20-github.md b/docs/docs/30-administration/11-forges/20-github.md index 08adc9ec7d..adf63c344b 100644 --- a/docs/docs/30-administration/11-forges/20-github.md +++ b/docs/docs/30-administration/11-forges/20-github.md @@ -3,9 +3,10 @@ Woodpecker comes with built-in support for GitHub and GitHub Enterprise. To use Woodpecker with GitHub the following environment variables should be set for the server component: -```diff -+ - WOODPECKER_GITHUB_CLIENT=${WOODPECKER_GITHUB_CLIENT} -+ - WOODPECKER_GITHUB_SECRET=${WOODPECKER_GITHUB_SECRET} +```sh +WOODPECKER_GITHUB=true +WOODPECKER_GITHUB_CLIENT=YOUR_GITHUB_CLIENT_ID +WOODPECKER_GITHUB_SECRET=YOUR_GITHUB_CLIENT_SECRET ``` You will get these values from GitHub when you register your application. @@ -22,7 +23,7 @@ To do so, go to Settings -> Developer Settings -> GitHub Apps -> New GitHub App. ## App Permissions -The app must be granted the following permissions: +The app must be granted the following permissions (under App Settings -> Permissions): Repository: @@ -42,7 +43,7 @@ Account: - Email addresses: Read-only -## Client Secret +## Client Secret Creation After your App has been created, you can generate a client secret. Use this one for the `WOODPECKER_GITHUB_SECRET` environment variable. From 08ce09e2050766295f036933d0ef3e00638c5364 Mon Sep 17 00:00:00 2001 From: Patrick Schratz Date: Mon, 18 Sep 2023 23:12:00 +0200 Subject: [PATCH 3/3] Update docs/docs/30-administration/11-forges/20-github.md Co-authored-by: Lauris BH --- docs/docs/30-administration/11-forges/20-github.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/30-administration/11-forges/20-github.md b/docs/docs/30-administration/11-forges/20-github.md index adf63c344b..0911e795f4 100644 --- a/docs/docs/30-administration/11-forges/20-github.md +++ b/docs/docs/30-administration/11-forges/20-github.md @@ -66,7 +66,7 @@ This is a full list of configuration options. Please note that many of these opt - `WOODPECKER_GITHUB_SECRET` - Configures the GitHub OAuth client secret. This is used to authorize access. (Default: empty) -- `WOODPECKER_GITHUB_SECRET_FILE` - Read the value for `WOODPECKER_GITHUB_SECRET` from the specified filepath 9Default: empty) +- `WOODPECKER_GITHUB_SECRET_FILE` - Read the value for `WOODPECKER_GITHUB_SECRET` from the specified filepath (Default: empty) `WOODPECKER_GITHUB_MERGE_REF` - (Default: `true`)