forked from woodpecker-ci/woodpecker
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Update GH app installation instructions (woodpecker-ci#2472)
- Slimify - Add required permissions (missing so far) - More detailed instructions on app settings - Align env var options to style used in k8s section (UL instead of headers) --------- Co-authored-by: Lauris BH <lauris@nix.lv>
- Loading branch information
Showing
1 changed file
with
48 additions
and
47 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,72 +1,73 @@ | ||
| # 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: | ||
|
|
||
| ```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: | ||
| [...] | ||
| 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: | ||
|
|
||
| ```sh | ||
| WOODPECKER_GITHUB=true | ||
| WOODPECKER_GITHUB_CLIENT=YOUR_GITHUB_CLIENT_ID | ||
| WOODPECKER_GITHUB_SECRET=YOUR_GITHUB_CLIENT_SECRET | ||
| ``` | ||
|
|
||
| ## 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 `<scheme>://<host>/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://<your-woodpecker-instance>/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 | ||
|
|
||
|  | ||
| ## App Permissions | ||
|
|
||
| ## Configuration | ||
| The app must be granted the following permissions (under App Settings -> 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 Creation | ||
|
|
||
| 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 (Default: 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`) |