Skip to main content

Create App from GitHub

Appliku integrates with GitHub using token-based authentication. You create a personal access token in GitHub and provide it to Appliku, which then accesses your repositories for deployment, including automatic push-to-deploy.

Prerequisites​

  • A GitHub account with access to the repository you want to deploy
  • At least one server connected to Appliku

Step 1: Create a GitHub Access Token​

Appliku supports both fine-grained personal access tokens and classic PATs. See GitHub Token Permissions below for exactly which permissions to choose.

  1. Log in to your GitHub account
  2. Go to Settings > Developer settings > Personal access tokens
  3. Choose Fine-grained tokens (recommended) or Tokens (classic)
  4. Give the token a descriptive name (e.g., "Appliku deployment") and set an expiration
  5. For a fine-grained token, select the repository or repositories you want Appliku to deploy from, then grant the permissions described in GitHub Token Permissions
  6. Click Generate token
  7. Copy the token immediately: it will not be shown again

Step 2: Set Up GitHub Credentials in Appliku​

  1. Go to Applications > Add Application > GitHub
  2. Click Setup Credentials
  3. Enter your GitHub access token
  4. Save the credentials

Appliku verifies the token and connects to your GitHub account.

Step 3: Select Repository and Branch​

After connecting your GitHub account:

  1. Select a repository from the list of your accessible repositories. If you are using a fine-grained token scoped to specific repositories, Appliku may not be able to list every repository in your account. That is expected: you can enter the repository directly as owner/repo, and Appliku validates access to it before saving.
  2. Choose a branch to deploy from (e.g., main, master, or any feature branch)

Step 4: Choose a Server​

Select the server (standalone mode) or cluster (cluster mode) where you want to deploy the application.

Step 5: Name Your Application​

Give your application a name. This name is used to:

  • Identify the application in the Appliku dashboard
  • Generate the default subdomain (your-app-name.applikuapp.com)

Application names must be unique within your team and consist of lowercase letters, numbers, and hyphens.

Step 6: Create the Application​

Click Create Application. Appliku will:

  1. Set up the connection to your GitHub repository
  2. Register a webhook for push-to-deploy (when enabled)
  3. Create the application in your dashboard

Push-to-Deploy​

Push-to-deploy is enabled by default for GitHub applications. Every time you push to the configured branch, Appliku automatically triggers a new deployment.

You can verify the webhook is active in your GitHub repository under Settings > Webhooks.

GitHub Token Permissions​

Appliku works with both fine-grained personal access tokens and classic PATs. A fine-grained token scoped to the repositories you deploy is the recommended choice.

When creating a fine-grained token, select the repository (or repositories) you want Appliku to deploy from, and grant these repository permissions:

  • Contents: Read: required for deploying private repositories, so Appliku can clone and build your code and read branch contents.
  • Metadata: Read: required for repository and branch selection. GitHub includes this automatically for fine-grained tokens.
  • Webhooks: Read and Write: required only for automatic push-to-deploy. Appliku creates a webhook on your repository to trigger deployments on push. See GitHub's permissions for fine-grained tokens.

If you omit the Webhooks permission, manual deployments still work; only automatic push-to-deploy setup is unavailable. When that happens, Appliku shows an actionable error and leaves push-to-deploy off rather than failing silently.

A fine-grained token scoped to a single private repository is enough to create and deploy an app from that repository.

Classic PAT fallback​

If you prefer a classic token, the repo scope is the practical choice for cloning and accessing private repositories through the API. Be aware that repo is broader than a fine-grained token: it grants access to all of your repositories, so prefer a fine-grained token when you can.

Token expiry and revocation​

If your token expires or is revoked, deployments and branch lookups fail until you update the credentials in Appliku with a new token.

What you may still see, and what Appliku checks​

GitHub's permission behavior can be subtle, so the repositories or branches you can browse are not always the ones a token can actually deploy:

  • Repository and branch metadata can be visible even when a token is not scoped for deployment. This is most common with public repositories, whose contents and branches are readable by almost any token, so you may see branches listed for a repository you did not select for the token.
  • To avoid surprises at deploy time, Appliku validates the selected repository and branch before saving the application. Creation or a repository change is rejected up front, with a clear message, if the token cannot read the repository contents for that branch (Contents: Read).
  • Webhook permission is checked only when push-to-deploy is enabled. If the token can read and clone the repository but lacks Webhooks: Read and Write, the app is still created and deployable: Appliku turns push-to-deploy off, notifies you, and lets manual deployments continue. App creation does not get stuck waiting on webhook setup.

If you want push-to-deploy on a repository where it was disabled this way, add Webhooks: Read and Write for that repository to the token and re-enable push-to-deploy.

Next Steps​

After creating your application, you need to configure it before deploying: