diff --git a/src/hooks.server.ts b/src/hooks.server.ts index a75880c745..37986bbe4a 100644 --- a/src/hooks.server.ts +++ b/src/hooks.server.ts @@ -98,7 +98,7 @@ const securityheaders: Handle = async ({ event, resolve }) => { 'font-src': "'self'", 'object-src': "'none'", 'base-uri': "'self'", - 'form-action': "'self'", + 'form-action': "'self' https://github.com", 'frame-ancestors': join(["'self'", 'https://www.youtube.com', 'https://*.vimeo.com']), 'block-all-mixed-content': '', 'upgrade-insecure-requests': '', @@ -116,7 +116,8 @@ const securityheaders: Handle = async ({ event, resolve }) => { 'https://hemsync.clickagy.com', 'https://ws.zoominfo.com ', 'https://*.cookieyes.com', - 'https://cdn-cookieyes.com' + 'https://cdn-cookieyes.com', + 'https://api.github.com' ]), 'frame-src': join([ "'self'", diff --git a/src/markdoc/tags/GitHub_App_Form.svelte b/src/markdoc/tags/GitHub_App_Form.svelte new file mode 100644 index 0000000000..80e91ed399 --- /dev/null +++ b/src/markdoc/tags/GitHub_App_Form.svelte @@ -0,0 +1,284 @@ + + +
+ {#if loading} +

Setting up GitHub App...

+

Completing registration with GitHub.

+ {:else if error} +

Setup failed

+

{error}

+ + {:else if appConfig} +

GitHub App created

+

+ Set these environment variables in .env file of your Appwrite instance: +

+ +
+ +
+ {:else} +

Create GitHub App

+
{ + e.preventDefault(); + submit(); + }} + class="flex flex-col gap-5" + > +
+ + +

+ Domain of your Appwrite instance, without https:// +

+
+ +
+ + setIsOrganization(value)} + /> +
+ + {#if isOrganization} +
+ + +

+ The organization handle: https://github.com/[THIS_PART] +

+
+ {/if} + + +
+ {/if} +
diff --git a/src/markdoc/tags/_Module.svelte b/src/markdoc/tags/_Module.svelte index a7a8022ac1..d95f8fdba9 100644 --- a/src/markdoc/tags/_Module.svelte +++ b/src/markdoc/tags/_Module.svelte @@ -23,4 +23,5 @@ export { default as Storage_Image } from './Storage_Image.svelte'; export { default as Video_Card } from './Video_Card.svelte'; export { default as Appwrite_Network_Map } from '../../lib/components/appwrite-network/map.svelte'; + export { default as GitHub_App_Form } from './GitHub_App_Form.svelte'; diff --git a/src/partials/configure-github-app.md b/src/partials/configure-github-app.md index 8d72cf3f6b..0f24f5a474 100644 --- a/src/partials/configure-github-app.md +++ b/src/partials/configure-github-app.md @@ -4,15 +4,25 @@ Appwrite supports automatic deployments through Git integration. In order for Ap For automatic Git deployment to work, Appwrite needs to receive communication from GitHub, this means your Appwrite project must be accessible on the internet. If you're running on `localhost`, you need to run a proxy like [ngrok](https://ngrok.com/). -## GitHub App name {% #github-app-name %} +## Automatic GitHub app setup {% #automatic-github-app-setup %} + +We have built a simple form that utilizes [GitHub app manifest](https://docs.github.com/en/apps/sharing-github-apps/registering-a-github-app-from-a-manifest) to automatically pre-configure your GitHub app. Use below interface to create your app quickly. + +{% github_app_form /%} + +## Manual GitHub app setup {% #manual-github-app-setup %} + +You can create your GitHub app manually by filling [GitHub app creation form](https://github.com/settings/apps/new) with the following configurations. + +### GitHub App name {% #github-app-name %} The GitHub App name will be displayed when connecting Appwrite to GitHub. In addition, this name will be transformed to a slug ("My GitHub App" will become "my-github-app") and appear in the URL when accessing your app in GitHub. This slug should be set as the `_APP_VCS_GITHUB_APP_NAME` environment variable in Appwrite. -## Homepage URL {% #github-homepage-url %} +### Homepage URL {% #github-homepage-url %} The homepage URL will appear when looking at the public page of your app. It can be any URL you'd like. -## Callback URL {% #callback %} +### Callback URL {% #callback %} GitHub will use **callback URLs** to redirect users back to Appwrite. Set these callback URLs under **Identifying and authorizing users** in the same order as listed below. @@ -23,17 +33,17 @@ GitHub will use **callback URLs** to redirect users back to Appwrite. Set these Also, check the **Request user authentication (OAuth) during installation** box. -## Post installation {% #post-install %} +### Post installation {% #post-install %} Check the **Redirect on update** box under the **Post installation** section. -## Webhook {% #github-webhooks %} +### Webhook {% #github-webhooks %} GitHub will notify Appwrite about events like new commits using webhooks. Under **Webhook**, you need to check the **Active** checkbox. You also need to set the **Webhook URL** as `https:///v1/vcs/github/events`. If you're running Appwrite on `localhost`, GitHub can't send requests to Appwrite through webhooks and automatic deployments won't work. You'll need to host Appwrite on a server or use a proxy like [ngrok](https://ngrok.com/) to make Appwrite accessible to GitHub. -## Repository permissions {% #repository-permission %} +### Repository permissions {% #repository-permission %} Configure these permissions under the **Repository permission** dropdown. @@ -48,7 +58,7 @@ Configure these permissions under the **Repository permission** dropdown. | Pull requests | Read and write | | Webhooks | Read and write | -## Account permissions {% #account-permission %} +### Account permissions {% #account-permission %} Configure these permissions under the **Account Permission** dropdown. @@ -56,7 +66,7 @@ Configure these permissions under the **Account Permission** dropdown. | ------------- | --------- | | Email address | Read-only | -## Subscribe to events {% #subscribe-events %} +### Subscribe to events {% #subscribe-events %} Select these under the **Subscribe to events** dropdown. @@ -65,46 +75,6 @@ Select these under the **Subscribe to events** dropdown. | Pull request | | Push | -## Where can this GitHub App be installed? {% #github-where-installed %} +### Where can this GitHub App be installed? {% #github-where-installed %} Check the **Any account** box under **Where can this GitHub App be installed?** section. This is important to allow you to install the GitHub app on multiple Appwrite projects. - -## Environment variables {% #github-variables %} - -After creating your app, you'll have to configure the following environment variables. - -| Variable | Description | -| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `_APP_DOMAIN` | Your main Appwrite domain used to access the Appwrite Console. When setting a public suffix domain, Appwrite will attempt to issue a valid SSL certificate automatically. When used with a dev domain, Appwrite will assign a self-signed SSL certificate. If you're using a proxy for **localhost development**, such as [ngrok](https://ngrok.com/), this will be the domain of your localhost proxy. | -| `_APP_DOMAIN_TARGET` | A hostname to serve as a CNAME target for your Appwrite custom domains. You can use the same value as used for the Appwrite `_APP_DOMAIN` variable. If you're using a proxy for **localhost development**, such as [ngrok](https://ngrok.com/), this will be the domain of your localhost proxy, such as `dd65-2405-201-4013-d8d7-b4c5-fb73-39f9-285c.ngrok.io`. | -| `_APP_DOMAIN_FUNCTIONS` | This will be used for system generated [Function Domains](/docs/products/functions/domains). When a function domain is generated, it will be `[UNIQUE_ID].[_APP_DOMAIN_FUNCTIONS]`. If `_APP_DOMAIN_FUNCTIONS` is set to `example.com` for example, the generated domain for functions will be something like `64d4d22db370ae41a32e.example.com`. You can use the same value as used for the Appwrite `_APP_DOMAIN` variable. | -| `_APP_DOMAIN_SITES` | This will be used for system generated [Site Domains](/docs/products/sites/domains). When a site domain is generated, it will be `[UNIQUE_ID].[_APP_DOMAIN_SITES]`. If `_APP_DOMAIN_SITES` is set to `example.com` for example, the generated domain for sites will be something like `64d4d22db370ae41a32e.example.com`. You can use the same value as used for the Appwrite `_APP_DOMAIN` variable. | -| `_APP_VCS_GITHUB_APP_NAME` | Name of your GitHub app. This is the display name you'll see on GitHub and it will be visible in your GitHub app's URL. | -| `_APP_VCS_GITHUB_PRIVATE_KEY` | RSA private key from GitHub wrapped with double quotes and newlines replaced with `\n`. You can generate private keys from GitHub application settings. | -| `_APP_VCS_GITHUB_APP_ID` | GitHub application ID. You can find it in your GitHub application details. | -| `_APP_VCS_GITHUB_CLIENT_ID` | GitHub client ID. You can find it in your GitHub application details. | -| `_APP_VCS_GITHUB_CLIENT_SECRET` | GitHub client secret. You can generate secrets in your GitHub application settings. | -| `_APP_VCS_GITHUB_WEBHOOK_SECRET` | GitHub webhook secret. You can configure it in your GitHub application settings under webhook section. | - -For example, see below. - -```bash -_APP_DOMAIN=appwrite.example.com -_APP_DOMAIN_TARGET=appwrite.example.com -_APP_DOMAIN_FUNCTIONS=functions.example.com -_APP_VCS_GITHUB_APP_NAME=my-github-app -_APP_VCS_GITHUB_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----\nMIIEogIBAAKCAQEAuT8f3lo/X83hfvb0ZN/KD2pl86o/jl3ywKrkj/PQZBmtEv/z\nIugE//sfFoHWc4cizkcji+n3FNU+GEdvMioKuJlPBqPTY8hAbVn7R0geZLpDV/rs\n[...]\n-----END RSA PRIVATE KEY-----" -_APP_VCS_GITHUB_APP_ID=12415 -_APP_VCS_GITHUB_CLIENT_ID=Iv1.35asdf43asd -_APP_VCS_GITHUB_CLIENT_SECRET=35rsdse532q13 -_APP_VCS_GITHUB_WEBHOOK_SECRET=super-secret -``` - -[Learn more about environment variables](/docs/advanced/self-hosting/environment-variables) - -## Update existing GitHub apps {% #existing-apps %} - -There are additional steps if you're updating permissions in existing GitHub apps. -Every time you update your GitHub app's permissions, GitHub will prompt you to review the changes. -You will receive an email and you'll find a prompt under **Settings** > **Integrations** > **Applications** > **Installed GitHub Apps** > find your GitHub app > **Configure**. -You need to accept the new permissions so they're applied to your app. diff --git a/src/routes/docs/advanced/self-hosting/configuration/version-control/+page.markdoc b/src/routes/docs/advanced/self-hosting/configuration/version-control/+page.markdoc index 33d2c12066..a07a0676c2 100644 --- a/src/routes/docs/advanced/self-hosting/configuration/version-control/+page.markdoc +++ b/src/routes/docs/advanced/self-hosting/configuration/version-control/+page.markdoc @@ -6,7 +6,49 @@ description: Configure version control integration for Functions and Sites in yo {% partial file="configure-github-app.md" /%} -## Apply configuration +# Connect GitHub app to Appwrite instance {% #connect %} + +## Environment variables {% #github-variables %} + +After creating your app, you'll have to configure the following environment variables. + +| Variable | Description | +| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `_APP_DOMAIN` | Your main Appwrite domain used to access the Appwrite Console. When setting a public suffix domain, Appwrite will attempt to issue a valid SSL certificate automatically. When used with a dev domain, Appwrite will assign a self-signed SSL certificate. If you're using a proxy for **localhost development**, such as [ngrok](https://ngrok.com/), this will be the domain of your localhost proxy. | +| `_APP_DOMAIN_TARGET` | A hostname to serve as a CNAME target for your Appwrite custom domains. You can use the same value as used for the Appwrite `_APP_DOMAIN` variable. If you're using a proxy for **localhost development**, such as [ngrok](https://ngrok.com/), this will be the domain of your localhost proxy, such as `dd65-2405-201-4013-d8d7-b4c5-fb73-39f9-285c.ngrok.io`. | +| `_APP_DOMAIN_FUNCTIONS` | This will be used for system generated [Function Domains](/docs/products/functions/domains). When a function domain is generated, it will be `[UNIQUE_ID].[_APP_DOMAIN_FUNCTIONS]`. If `_APP_DOMAIN_FUNCTIONS` is set to `example.com` for example, the generated domain for functions will be something like `64d4d22db370ae41a32e.example.com`. You can use the same value as used for the Appwrite `_APP_DOMAIN` variable. | +| `_APP_DOMAIN_SITES` | This will be used for system generated [Site Domains](/docs/products/sites/domains). When a site domain is generated, it will be `[UNIQUE_ID].[_APP_DOMAIN_SITES]`. If `_APP_DOMAIN_SITES` is set to `example.com` for example, the generated domain for sites will be something like `64d4d22db370ae41a32e.example.com`. You can use the same value as used for the Appwrite `_APP_DOMAIN` variable. | +| `_APP_VCS_GITHUB_APP_NAME` | Name of your GitHub app. This is the display name you'll see on GitHub and it will be visible in your GitHub app's URL. | +| `_APP_VCS_GITHUB_PRIVATE_KEY` | RSA private key from GitHub wrapped with double quotes and newlines replaced with `\n`. You can generate private keys from GitHub application settings. | +| `_APP_VCS_GITHUB_APP_ID` | GitHub application ID. You can find it in your GitHub application details. | +| `_APP_VCS_GITHUB_CLIENT_ID` | GitHub client ID. You can find it in your GitHub application details. | +| `_APP_VCS_GITHUB_CLIENT_SECRET` | GitHub client secret. You can generate secrets in your GitHub application settings. | +| `_APP_VCS_GITHUB_WEBHOOK_SECRET` | GitHub webhook secret. You can configure it in your GitHub application settings under webhook section. | + +For example, see below. + +```bash +_APP_DOMAIN=appwrite.example.com +_APP_DOMAIN_TARGET=appwrite.example.com +_APP_DOMAIN_FUNCTIONS=functions.example.com +_APP_VCS_GITHUB_APP_NAME=my-github-app +_APP_VCS_GITHUB_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----\nMIIEogIBAAKCAQEAuT8f3lo/X83hfvb0ZN/KD2pl86o/jl3ywKrkj/PQZBmtEv/z\nIugE//sfFoHWc4cizkcji+n3FNU+GEdvMioKuJlPBqPTY8hAbVn7R0geZLpDV/rs\n[...]\n-----END RSA PRIVATE KEY-----" +_APP_VCS_GITHUB_APP_ID=12415 +_APP_VCS_GITHUB_CLIENT_ID=Iv1.35asdf43asd +_APP_VCS_GITHUB_CLIENT_SECRET=35rsdse532q13 +_APP_VCS_GITHUB_WEBHOOK_SECRET=super-secret +``` + +[Learn more about environment variables](/docs/advanced/self-hosting/environment-variables) + +## Update existing GitHub apps {% #existing-apps %} + +There are additional steps if you're updating permissions in existing GitHub apps. +Every time you update your GitHub app's permissions, GitHub will prompt you to review the changes. +You will receive an email and you'll find a prompt under **Settings** > **Integrations** > **Applications** > **Installed GitHub Apps** > find your GitHub app > **Configure**. +You need to accept the new permissions so they're applied to your app. + +## Apply configuration {% #apply-configuration %} After creating your GitHub App, restart your Appwrite services to apply the configuration: @@ -14,7 +56,7 @@ After creating your GitHub App, restart your Appwrite services to apply the conf docker compose up -d ``` -## Verify configuration +## Verify configuration {% #verify-configuration %} To verify that your GitHub App is correctly configured: @@ -23,7 +65,14 @@ To verify that your GitHub App is correctly configured: 3. Try creating a new Function or Site using GitHub as the source. 4. You should be prompted to install your GitHub App on your repositories. -## Troubleshooting +## Update existing GitHub apps {% #existing-apps %} + +There are additional steps if you're updating permissions in existing GitHub apps. +Every time you update your GitHub app's permissions, GitHub will prompt you to review the changes. +You will receive an email and you'll find a prompt under **Settings** > **Integrations** > **Applications** > **Installed GitHub Apps** > find your GitHub app > **Configure**. +You need to accept the new permissions so they're applied to your app. + +## Troubleshooting {% #troubleshooting %} If you encounter issues with your GitHub App integration: