keepcalculator

06 Numbers and Powers

Deploy to Cloudways From GitHub Actions With Access Token

Card No. 06·70993 · Updated · Standard formula, shown below

Yes, you can deploy to Cloudways from GitHub Actions using an access token. The token authenticates your workflow to the Cloudways API, letting you trigger a deployment of your application without storing a password or SSH key in the repository. This guide walks through the exact setup, the API calls involved, and the common pitfalls to avoid.

Background: Why Use an Access Token for Cloudways Deployments

Cloudways is a managed cloud hosting platform that supports PHP, WordPress, Laravel, and other applications. Its native deployment options include Git integration through the control panel, but that requires manual clicks or a separate webhook. For automated, event-driven deployments from a GitHub repository, the Cloudways API is the official path. The API authenticates with an email and API key, but using a dedicated access token—created in the Cloudways platform—keeps your main API credentials out of the workflow file. This is a more secure and revocable approach than embedding a password or a personal access token with broad permissions.

How It Works: The Cloudways API and Deployment Endpoint

Cloudways exposes a REST API at api.cloudways.com/api/v1. To deploy from GitHub Actions, your workflow must:

  1. Get an OAuth token from the API using your email and API key (or use a pre-generated access token if your Cloudways plan supports it).
  2. Call the deployment endpoint for your application and server.
  3. Pass the GitHub commit hash or branch name so Cloudways pulls the correct code.

The key endpoint is POST /api/v1/git/deploy. It requires the server ID, application ID, and a git_url pointing to your repository. The API returns a deployment ID that you can poll to check status. A typical workflow uses curl or PowerShell to make these requests, with the token stored as a GitHub secret.

Step-by-Step: Setting Up the GitHub Actions Workflow

Here is a practical sequence to get a deployment working. You will need your Cloudways API key and email, which you generate from the Cloudways console under Account > API > API Keys.

  1. Create secrets in GitHub: Go to your repository Settings > Secrets and variables > Actions. Add CLOUDWAYS_API_KEY, CLOUDWAYS_EMAIL, and optionally CLOUDWAYS_TOKEN if you have a dedicated access token.
  2. Write the workflow file: In .github/workflows/deploy.yml, define a trigger (e.g., push to main) and a job that runs on ubuntu-latest.
  3. Obtain an OAuth token: Use curl to POST to https://api.cloudways.com/api/v1/oauth/access_token with your email and API key. The response contains an access_token valid for a short time.
  4. Call the deploy endpoint: With the token in an Authorization header, POST to https://api.cloudways.com/api/v1/git/deploy with JSON body containing server_id, app_id, git_url, and branch_name.
  5. Check the response: The API returns a deployment_id. You can then poll GET /api/v1/git/deployment_status to wait for completion.

Common Problems and How to Avoid Them

Several issues trip up developers new to this integration:

  • Wrong API endpoint: The OAuth token endpoint is /oauth/access_token, not /oauth/token. Double-check the path.
  • Expired tokens: OAuth tokens from the API expire after a short period (typically 1 hour). Always generate a fresh token inside the workflow, not a static one.
  • Incorrect server or app ID: Find these in the Cloudways console URL or via the API’s /server and /app endpoints. They are numeric IDs, not names.
  • Git URL format: Use the HTTPS URL of your repository (e.g., https://github.com/username/repo.git), not the SSH form, unless you have configured SSH keys on the server.
  • Branch name mismatch: The branch must exist in the repository and match exactly. Use main or master as appropriate.

Using a Dedicated Access Token vs. API Key

Cloudways historically used only email/API key authentication. Newer plans and API versions support generating a dedicated access token from the console. This token can be stored directly as a GitHub secret and used in the Authorization header without the OAuth step. It is more secure because you can revoke it independently of your main API key. If your account does not show this option, stick with the OAuth flow described above—it works reliably. The token you store in GitHub should have the minimum scope needed; Cloudways tokens typically grant full API access, so treat them like a password.

Security Best Practices for Tokens in GitHub Actions

Storing secrets in GitHub Actions is safe if you follow these rules:

  • Never hardcode tokens in the workflow file or commit them to the repository.
  • Use GitHub’s encrypted secrets, which are masked in logs.
  • Limit the workflow’s permissions to the minimum (e.g., contents: read) and avoid using pull_request_target unless you understand the risks.
  • Rotate the token periodically, especially if you suspect a leak.
  • Consider using a dedicated deployment user or token that can be revoked without affecting other services.

Alternatives: Webhooks and Native Git Integration

If you prefer not to use GitHub Actions, Cloudways offers a native Git integration in the application’s Deployment tab. You can connect your repository and deploy with a click, but it does not trigger automatically on every push. For automation, you can also set up a webhook from GitHub to Cloudways, but that requires a publicly accessible URL and does not give you the same control over the build process. GitHub Actions is the most flexible because you can run tests, build assets, and then deploy—all in one pipeline.

Frequently Asked Questions

Can I use a personal access token from GitHub instead?

No—the token must be a Cloudways API token. GitHub’s personal access token is for GitHub authentication, not for Cloudways. You need to generate a token from Cloudways (or use your API key) to authenticate with their API.

What if my repository is private?

Cloudways needs access to the repository. If it is private, you must provide a Git URL with credentials (e.g., https://username:token@github.com/...) or configure an SSH key on the Cloudways server. The API’s git_url field accepts a URL with embedded credentials, but be careful not to expose them in logs—use GitHub secrets in the workflow to construct the URL.

How do I find my server ID and application ID?

Log into Cloudways, select your server, and look at the URL—it contains the server ID (e.g., server/12345). The application ID is in the application’s URL or in the API response when you list applications via GET /api/v1/app.

Can I deploy a specific commit hash instead of a branch?

Yes, the Cloudways API accepts a git_url and a branch_name, but you can also specify a commit hash by setting the branch to the full hash. However, Cloudways may treat it as a branch name, so it is safer to push a tag and deploy that tag.

Is there a way to see deployment logs from GitHub Actions?

Yes, the API returns a deployment_id, and you can poll the status endpoint. The workflow logs will show the API responses, but the actual build logs from Cloudways are visible in the Cloudways console under the application’s Deployment tab.

What happens if the deployment fails?

The API returns a non-200 status code or a failure message. Your workflow should check the response and exit with a non-zero code to mark the job as failed. You can also set up notifications via GitHub Actions’ built-in features to alert you on failure.

Related

Method: the standard formula for this calculation, rounded as each result states. See how the calculators work or report an error.

More cards in this drawer

The whole Numbers and Powers drawer →