Skip to content

Automatic updates

Configure automatic deployment after verifying manual Git pull and the deployment script. Open its configuration in the project.

Trigger modes

  • Periodic: the regular-check option performs minute-based verification; an update is queued when newer code is confirmed available.
  • Scheduled time: uses the time offered by the form.
  • Webhook: a supported message from the Git provider triggers the update.
  • Off: automatic updates do not run.

Automatic processing depends on the service scheduler and task processing. Saving a mode does not guarantee immediate deployment.

Webhook

  1. Select webhook mode and save it.
  2. Copy the webhook address from the project interface.
  3. Reveal the webhook secret and configure the same value at the provider.
  4. For GitHub, select content type application/json. Select push events (GitHub or GitLab) for the branch configured in the project and verify an actual push.
  5. Check delivery at the provider and the resulting project operation.

The secret protects message verification; do not publish it. Disabling automatic deployment removes the stored secret. After enabling webhook mode again, check the provider configuration too.

An initial ping or a push to another branch may trigger nothing. Successful webhook acceptance alone does not confirm deployment.

GitHub webhook returns error 422

A 422 response means the endpoint could not decode the request body as JSON. A common cause is setting Content type to application/x-www-form-urlencoded: GitHub then sends JSON inside a form parameter named payload, which this endpoint does not process. Secret verification happens before JSON decoding, so the signature has already passed verification when this response is returned.

  1. In the GitHub repository, open Settings → Webhooks → your webhook.
  2. Set Content type → application/json and save with Update webhook.
  3. Make a new push to the branch configured in the project.
  4. Open the new delivery in Recent Deliveries and check the response. The expected status is 202; accepting the message alone does not confirm deployment completion.

If the error persists, inspect the delivery's Content-Type header, request body and Response body. An invalid or missing signature returns 401. When sharing diagnostics, do not disclose the secret or sensitive payload data. See the GitHub documentation for details about payload formats.

Changes are not deployed

File ownership and permissions

Repository updates do not recursively change the owner or group of project files. Provision repository access for the Git user beforehand; pulling does not automatically repair missing access by changing ownership. Git may replace tracked files during updates, so keep runtime data out of versioned files.

In the deployment script settings, choose a user with appropriate project access. Laravel also requires PHP and workers to write to storage and bootstrap/cache. Configure shared access once using appropriate ownership, groups and permission inheritance or ACLs. Legacy deployment scripts without saved user settings run as root and may create root-owned files; save their settings with the appropriate user. The pull fix does not restore ownership changed by previous deployments.

Check the selected branch, repository access, webhook delivery and operation history. An ongoing operation may block concurrent execution. Diagnose repeated failure through the manual workflow first.

Preparing a manually added repository

If you cloned a project on the VM manually, for example as root, automatic inspection may require both local permissions and GitHub access. These are separate steps: fixing file permissions does not grant access to a private repository.

This procedure is for GitHub and Debian/Ubuntu. Run the commands in the same SSH or VNC console as root or a user with sudo access. These commands do not deploy anything; the final step only fetches Git metadata. Deployment may require additional permissions for working files.

1. Enter the actual project path and Git user

Copy the path from the project overview in the cloud. Enter the full repository path, rather than its parent directory. The Git user is usually grapeCloud; if your VM has another configured login user, enter that name instead. Usernames are case sensitive.

read -r -p 'Full project path from the cloud: ' REPO_PATH
read -r -p 'Git user [grapeCloud]: ' GIT_USER
GIT_USER="${GIT_USER:-grapeCloud}"
GIT_HOME="$(getent passwd "$GIT_USER" | cut -d: -f6)"

# Inspection uses the root key when the user's key is missing.
if ! sudo test -r "$GIT_HOME/.ssh/id_rsa" && [ "$GIT_USER" != root ] && sudo test -r /root/.ssh/id_rsa; then
    GIT_USER=root
    GIT_HOME=/root
fi
printf 'Project: %s\nGit user: %s\n' "$REPO_PATH" "$GIT_USER"

If the path or user is incorrect, repeat this step. If the entered user does not exist (getent passwd "$GIT_USER" prints nothing), correct the username first.

2. Fix local permissions only when access fails

For cannot open .git/FETCH_HEAD: Permission denied, use Copy commands in the project notice. It includes the acl installation, actual path and Git metadata permissions. Paste the entire block into the console. The commands preserve project ownership; ACL changes may modify the mask and the effective permissions of existing ACL entries.

If the notice is unavailable, this general block uses the values from step 1. If any command fails, resolve that error before proceeding to the next step.

sudo apt-get install -y acl && (
    set -eu
    GIT_DIR="$(sudo git -c safe.directory="$REPO_PATH" -C "$REPO_PATH" rev-parse --absolute-git-dir)"
    COMMON_DIR="$(sudo git -c safe.directory="$REPO_PATH" -C "$REPO_PATH" rev-parse --git-common-dir)"
    case "$COMMON_DIR" in
        /*) ;;
        *) COMMON_DIR="$REPO_PATH/$COMMON_DIR" ;;
    esac
    sudo test -d "$GIT_DIR"
    sudo test -d "$COMMON_DIR"
    PARENT="$(dirname "$REPO_PATH")"
    while [ "$PARENT" != / ] && [ "$PARENT" != . ]; do
        sudo setfacl -m "u:$GIT_USER:--x" -- "$PARENT"
        PARENT="$(dirname "$PARENT")"
    done
    sudo setfacl -m "u:$GIT_USER:r-x" -- "$REPO_PATH"
    for DIRECTORY in "$GIT_DIR" "$COMMON_DIR"; do
        sudo setfacl -R -m "u:$GIT_USER:rwX" -- "$DIRECTORY"
        sudo find "$DIRECTORY" -type d -exec setfacl -m "d:u:$GIT_USER:rwx" -- {} +
    done
)

3. Configure the actual SSH repository URL

The error could not read Username for 'https://github.com' means HTTPS credentials are unavailable to the automatic inspection. To use the project's SSH key, switch origin to SSH.

Open your actual repository on GitHub → Code → SSH and copy its URL. The commands below prompt you to paste it. Do not use the example names OWNER/REPOSITORY literally; the URL must contain the actual owner and repository name.

sudo -u "$GIT_USER" git -c safe.directory="$REPO_PATH" -C "$REPO_PATH" remote get-url origin
read -r -p 'SSH URL from GitHub → Code → SSH: ' REPO_SSH_URL
if [ -n "$REPO_SSH_URL" ]; then
    sudo -u "$GIT_USER" git -c safe.directory="$REPO_PATH" -C "$REPO_PATH" remote set-url origin "$REPO_SSH_URL"
    sudo -u "$GIT_USER" git -c safe.directory="$REPO_PATH" -C "$REPO_PATH" remote get-url origin
fi

Skip this step if your repository intentionally uses HTTPS with configured credentials. Those credentials must be available to the actual Git user without an interactive prompt.

4. Verify the SSH key and project access

sudo -u "$GIT_USER" ssh -T -o IdentitiesOnly=yes \
    -i "$GIT_HOME/.ssh/id_rsa" git@github.com

On first connection, verify the host key fingerprint against the GitHub documentation. The response You've successfully authenticated, but GitHub does not provide shell access confirms the SSH identity; this test normally exits with code 1. It does not confirm access to a particular repository.

If fetch reports Repository not found, check the origin URL and the recognized identity's access to the project. For a private repository, you can add the public key from the cloud under GitHub → Settings → Deploy keys → Add deploy key. Read access is enough for inspection and fetching. For an account SSH key, the recognized account must have access to the repository. Do not overwrite an existing key to resolve this error.

5. Verify fetch and wait for automatic inspection

sudo -u "$GIT_USER" env HOME="$GIT_HOME" \
    GIT_SSH_COMMAND="ssh -o IdentitiesOnly=yes -i $GIT_HOME/.ssh/id_rsa" \
    git -c safe.directory="$REPO_PATH" -C "$REPO_PATH" fetch origin

If the command finishes without an error, wait for the next automatic project inspection. The notice disappears only after that inspection succeeds, rather than immediately after pasting the repair commands. If fetch succeeds but inspection still fails, check the configured branch and whether it exists on origin. An empty branch field means the tracked or current branch is determined automatically.