Functions

Configure GitHub app

Appwrite supports automatic deployments through Git integration. In order for Appwrite to access your repos, you must create a GitHub app to enable this integration. The GitHub app requires the following configurations.

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.

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

The homepage URL will appear when looking at the public page of your app. It can be any URL you'd like.

Callback URL

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.

URLs
https://[HOSTNAME_OR_IP]/v1/vcs/github/callback
https://[HOSTNAME_OR_IP]/v1/account/sessions/oauth2/callback/github/console

Also, check the Request user authentication (OAuth) during installation box.

Post installation

Check the Redirect on update box under the Post installation section.

Webhook

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://[HOSTNAME_OR_IP]/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 to make Appwrite accessible to GitHub.

Repository permissions

Configure these permissions under the Repository permission dropdown.

PermissionAccess
AdministrationRead and write
ChecksRead and write
Commit StatusesRead and write
ContentsRead and write
IssuesRead and write
MetadataRead-only
Pull requestsRead and write
WebhooksRead and write

Account permissions

Configure these permissions under the Account Permission dropdown.

PermissionAccess
Email addressRead-only

Subscribe to events

Select these under the Subscribe to events dropdown.

Events
Pull request
Push

Where can this GitHub App be 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

After creating your app, you'll have to configure the following environment variables.

VariableDescription
_APP_DOMAINYour 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, this will be the domain of your localhost proxy.
_APP_DOMAIN_TARGETA 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, this will be the domain of your localhost proxy, such as dd65-2405-201-4013-d8d7-b4c5-fb73-39f9-285c.ngrok.io.
_APP_DOMAIN_FUNCTIONSThis will be used for system generated Function 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_VCS_GITHUB_APP_NAMEName 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_KEYRSA 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_IDGitHub application ID. You can find it in your GitHub application details.
_APP_VCS_GITHUB_CLIENT_IDGitHub client ID. You can find it in your GitHub application details.
_APP_VCS_GITHUB_CLIENT_SECRETGitHub client secret. You can generate secrets in your GitHub application settings.
_APP_VCS_GITHUB_WEBHOOK_SECRETGitHub 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

Update existing GitHub 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.

Configure Function runtimes

Not all function runtimes are enabled by default. Enable the runtimes that you need and disable unused runtimes to save disk space on your server. To enable a runtime, add it to the _APP_FUNCTIONS_RUNTIMES environment variable as a comma-separated list.

The example below would enable Dart 2.15, .NET 6.0, and Java 18 runtimes.

Bash
_APP_FUNCTIONS_RUNTIMES=dart-2.15,dotnet-6.0,java-18.0

You can find a full list of supported runtimes here.

You can also configure the maximum timeout that can be set on individual Appwrite Functions. The maximum configurable timeout can be increased by changing the _APP_FUNCTIONS_TIMEOUT environment variable. This environment variable changes the configurable maximum but does not alter existing configurations of individual functions.

Applying changes

After editing your docker-compose.yml or .env files, you will need to recreate your Appwrite stack by running the following compose command in your terminal.

Shell
docker compose up -d

You can verify if the changes have been successfully applied by running this command:

Shell
docker compose exec appwrite vars