A deploy token lets you upload your code to an App Platform app from your own computer or from a CI pipeline, without connecting GitHub. You package your project as a .tar.gz file and upload it with one curl command; the platform builds it and switches traffic to the new version.
In your app's Deploy Tokens tab, click Create Token. The token is shown once, together with a ready-to-run command that already contains your token and your app's deploy address. Package your project with tar, then run that command. Each token works for one app only, you can hold up to 5 per app, and uploads can be up to 512 MB. Copy the command from the tab rather than typing it: the deploy address isn't something to write from memory.
Deploy your first app takes you from an empty folder to a live site using a deploy token, one step at a time.
1. Create a token
- Open your appfrom App Platform in the client-area menu and go to Access › Deploy Tokens.
- Click Create Token.Give it a name that says where it will be used, such as
laptoporgithub-actions. - Choose an expiry:never, 30, 60 or 90 days, or 1 year.
- Copy the token and the ready-to-run commandstraight away, then click I've copied it, dismiss.
We store only a hash of the token, so we can't show it again or recover it. If you lose it, revoke that token and create a new one.
2. Package your code
Package the contents of your project folder, so that package.json (for Node.js) or your Dockerfile (for anything else) sits at the top of the archive. Leave out node_modules, .git and local secret files; the platform installs dependencies itself.
tar czf app.tar.gz --exclude=node_modules --exclude=.git --exclude=.env -C my-app .The -C my-app . part means "the contents of my-app", not the folder itself. Only Node.js is detected automatically; Python, PHP and other languages need a Dockerfile in the root of the project.
3. Upload it
Paste the command you copied from the Deploy Tokens tab, and run it from the folder that holds app.tar.gz. It has this shape:
curl -X POST <deploy address from the Deploy Tokens tab> \
-H "Authorization: Bearer <your deploy token>" \
-H "Content-Type: application/gzip" \
--data-binary @app.tar.gzIf you've lost the ready-made command, the tab's How to Deploy section shows the same command with your app's address and a placeholder for the token. Replace the placeholder with your token, keeping the word Bearer and the space after it.
The command waits while your app builds, then prints the result, including the build log. Dependencies are installed, the app is built and health-checked, and traffic switches to the new version with no downtime. If the build fails, the version that was already running keeps running. You can also follow the build in the Deploys tab.
4. Deploy from CI on every push
A deploy-token step in your CI is how you get deploy-on-push today; pushing to GitHub doesn't deploy on its own.
- Create a tokenfor the pipeline, named after it, for example
github-actions. - Store it as a secretin your CI settings, under the name the tab's example uses. Never paste the token into a file in your repository.
- Copy the jobfor GitHub Actions, GitLab CI or Bitbucket Pipelines from "From your CI, on every push" in the Deploy Tokens tab.
- Commit the job file.Each push to your main branch then packages the code and uploads it.
The copied job already contains your app's deploy address. See Deploying from GitHub for the GitHub side.
5. Managing tokens
The token list shows when each token was created, when it was last used, and when it expires. An expired token's deploys are rejected.
- Revoke a token the moment it's no longer needed, or if it may have been exposed. Any CI using it stops working.
- Up to 5 tokens per app. Revoke an old one to make room.
- One app per token. A token can't deploy to any of your other apps.
6. Common responses
| Response | What it means |
|---|---|
Missing Authorization: Bearer … (401) | The Authorization line is missing from your command |
Invalid or expired deploy token (401) | The token is wrong, expired or revoked; the placeholder is still in the command; or the app name in the command belongs to a different app |
A deploy is already in progress for this app (409) | Wait for the current deploy to finish, then try again |
Upload exceeds 512 MB (413) | Exclude node_modules, .git and large files |
Invalid archive (400) | The file isn't a gzipped tarball; create it with tar czf |
| Build starts, then fails | The upload worked; read the build log in the Deploys tab |
More fixes are in Troubleshooting the App Platform.
7. Keeping tokens safe
- Tokens are stored hashed; the plain token isn't kept after you create it.
- Store tokens only in your CI's secret settings or a password manager.
- Never commit a token to source control, and never paste one into a support ticket.
- Use a separate token for each machine or pipeline, so you can revoke one without breaking the others.
What is an App Platform deploy token?
A secret key that lets you upload your code to one App Platform app from your computer or a CI pipeline, without connecting GitHub. You create it in the app's Deploy Tokens tab.
I lost my deploy token. Can you show it again?
No. Only a hash is stored, so the token can't be shown again or recovered. Revoke it and create a new one.
Where do I get the deploy command?
When you create a token, the Deploy Tokens tab shows a ready-to-run command with your token and your app's deploy address filled in. Copy it from there rather than typing it.
How many deploy tokens can I have?
Up to 5 per app. Each token works for one app only.
How large can an upload be?
Up to 512 MB. Leave out node_modules and .git; the platform installs dependencies itself.
Can I deploy on every push with a token?
Yes. Store the token as a CI secret and add the ready-made GitHub Actions, GitLab CI or Bitbucket Pipelines job from the Deploy Tokens tab.
Ready to deploy? Open your App Platform apps, compare App Platform plans, or ask us in a support ticket.
Deploy tokens and GitHub deploys are included in every App Platform plan.
See App Platform plans