Triggering a Build¶
This page covers everything you need to run builds: the commands, the flags, how to monitor progress, and how to set up access to private repositories.
Your First Build¶
The Git repository URL is required — pass it with -g:
This clones the main branch, reads appmecca.yaml, builds all containers, and pushes the images to the private image registry. The command is fire-and-forget: it queues the build (and, by default, a deploy that runs when the build succeeds) and returns immediately with the build ID — it does not block. Track progress with mecca build status / mecca build logs.
Expected output
Command Flags¶
The build trigger command takes these flags:
| Flag | Short | Description |
|---|---|---|
--env |
-e |
Target environment (resolved from mecca.conf default when omitted) |
--git-url |
-g |
Git repository URL — required |
--branch |
-b |
Branch to build (default: main) |
--config-path |
Path to appmecca.yaml within the repository (default: appmecca.yaml) |
|
--no-deploy |
Build only — skip the automatic deploy that otherwise runs on build success |
Building a Specific Branch¶
By default, AppMecca builds the main branch. To build a different branch:
This is useful for testing feature branches in a development environment before merging. The branch build (and the deploy that follows it) runs completely isolated from main with its own database, ports, and URL. See Branch Deployments for the full guide.
Build Without Deploying¶
By default, a successful build is followed automatically by a deploy. To build only — push the image to the registry but not deploy it — pass --no-deploy:
This is useful when you want to inspect the build, or deploy it later with mecca app deploy, or build several branches before choosing which to deploy.
Build + deploy is the default
A plain mecca build trigger queues a build and a deploy that runs the moment the build succeeds (and is skipped if the build fails). --no-deploy opts out. There is no separate --deploy flag — deploy-on-success is already the default.
Watching Progress¶
build trigger is fire-and-forget — it returns the build ID immediately. Use the build ID to watch progress:
mecca build status <build-id> -e dev # one-shot status
mecca build logs <build-id> -e dev # read the build log
Checking Build Status¶
After triggering a build, check its status with the build ID:
The build ID can be a full UUID or a unique prefix — mecca build status -e dev 2d0ad0c2 resolves the same row.
Expected output
Where build status comes from¶
mecca build status searches two places in this order, so the same command works regardless of where in its lifecycle the build is:
- Deploy queue first (
/api/deployments/queue?all=true) — gives the live status while the build is queued or running, plus the structurederror_messagefield if it failed. Theall=trueflag is mandatory; without it, terminal rows would be filtered out. - Builds table fallback — for older builds that the queue has rotated out.
If you queue a redeploy via mecca app redeploy <app> and want to track its build, the action ID returned by that command is what you pass here — same lookup logic.
mecca build logs for early-failure builds¶
mecca build logs <id> works the same way — and also falls back to the deploy queue when the builds-table row is missing. A BUILD can fail before producing any build log (e.g. an authentication or config-path error during project setup), in which case there's no build log to fetch but the deploy queue's error_message carries the actual failure reason. The CLI surfaces it as the rendered message field with a source: queue hint so you know the failure happened during setup rather than during the build itself.
If you see Build '<id>' not found in builds table or deploy queue., both lookups failed — usually because the ID prefix doesn't match anything. Double-check the ID with mecca queue list -e <env>.
Build Statuses¶
| Status | Meaning |
|---|---|
IN_PROGRESS |
Build is currently running |
SUCCEEDED |
Build completed and images were pushed |
FAILED |
Build encountered an error (check logs) |
STOPPED |
Build was manually cancelled |
Viewing Build Logs¶
To view the full logs for a build:
For a multi-container build you can filter the output to lines mentioning one container by passing its name as a second argument:
Build logs are not streamed
mecca build logs prints a snapshot — there is no follow/tail flag. For an
in-progress build, re-run the command to see newer output, or use
mecca build status <id> to check whether it has finished.
No logs?
If a build failed before producing any output (e.g., Git clone failed), the build logs command will tell you and show the error message from the build status.
Listing Recent Builds¶
To see recent builds in an environment:
Expected output
Filtering by App¶
If you have multiple apps, filter the list to a specific one:
This shows only builds for myapp, ignoring builds from other applications.
Private Repositories¶
If your Git repository is private (most are), AppMecca needs credentials to clone it during builds. There are two authentication methods:
| Method | Best For | Scope |
|---|---|---|
| OAuth login | Interactive use, personal development | Per-user, stored locally |
| SSH deploy keys | CI/CD pipelines, shared environments | Per-environment, held in the platform secret store |
Option A: OAuth Login (Recommended)¶
The simplest way to authenticate. Log in with your GitHub or GitLab account:
This opens your browser for authentication via OAuth Device Authorization. Once authenticated, your token is stored locally in ~/.appmecca/tokens/ and used automatically when triggering builds.
Expected output
To check your login status:
To log out (removes the stored token):
OAuth tokens are per-user
OAuth tokens are stored on your machine only (~/.appmecca/tokens/). Each developer logs in independently. The token is passed securely to the build service during the build.
Option B: SSH Deploy Keys¶
For CI/CD pipelines and shared environments, use SSH deploy keys. These are held in the platform secret store and shared across all users in an environment.
Step 1: Generate an SSH Key¶
Expected output
This creates an Ed25519 SSH key pair and stores it securely in the platform secret store. The build service uses this key to clone your repositories.
If a key already exists for the environment, add --force to overwrite it:
Step 2: Get the Public Key¶
Copy the entire output (starting with ssh-ed25519).
Step 3: Add to Your Git Provider¶
Add the public key as a deploy key in your repository settings:
- Go to your repository on GitHub
- Click Settings (repository settings, not account settings)
- Click Deploy keys in the left sidebar
- Click Add deploy key
- Give it a title like
AppMecca dev - Paste the public key
- Leave "Allow write access" unchecked (AppMecca only needs read access)
- Click Add key
- Go to your repository on GitLab
- Click Settings > Repository
- Expand the Deploy keys section
- Enter a title like
AppMecca dev - Paste the public key
- Leave "Grant write permissions" unchecked
- Click Add key
- Go to your repository on Bitbucket
- Click Repository settings
- Click Access keys
- Click Add key
- Enter a label like
AppMecca dev - Paste the public key
- Click Add SSH key
One key per environment
Each AppMecca environment (dev, staging, prod) has its own SSH key. If you deploy to multiple environments, repeat this process for each one.
Checking Key Status¶
To verify that an SSH key exists for your environment:
Expected output
Removing a Key¶
If you need to rotate or remove the SSH key:
To skip the confirmation prompt, add --force:
After deleting, you need to run appmecca git-auth setup -e dev again and update the deploy key in your Git provider.
Using Builds in CI/CD¶
You can integrate AppMecca builds into your existing CI/CD pipeline. The mecca
CLI talks only to the AppMecca API, so a pipeline needs just two secrets:
APPMECCA_API_URL and APPMECCA_API_KEY. No cloud-provider credentials of any
kind are required.
GitHub Actions¶
# .github/workflows/deploy.yml
name: Build and Deploy
on:
push:
branches: [main]
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- name: Install AppMecca CLI
run: npm install -g appmecca
- name: Build and deploy
env:
APPMECCA_API_URL: ${{ secrets.APPMECCA_API_URL }}
APPMECCA_API_KEY: ${{ secrets.APPMECCA_API_KEY }}
run: |
mecca build trigger -e dev \
-g git@github.com:${{ github.repository }}.git \
-b ${{ github.ref_name }}
GitLab CI¶
# .gitlab-ci.yml
deploy:
stage: deploy
image: python:3.12-slim
variables:
APPMECCA_API_URL: $APPMECCA_API_URL
APPMECCA_API_KEY: $APPMECCA_API_KEY
script:
- npm install -g appmecca
- mecca build trigger -e dev
-g $CI_REPOSITORY_URL
-b $CI_COMMIT_BRANCH
only:
- main
build trigger does not wait — your pipeline step will pass early
mecca build trigger is fire-and-forget: it queues the build (and the
deploy that follows on success) and exits immediately with success, even
if the build later fails. There is no --wait or --no-wait flag.
If your pipeline needs to fail when the build fails, poll the returned build ID yourself:
BUILD_ID=$(mecca build trigger -e dev -g "$CI_REPOSITORY_URL" \
-b "$CI_COMMIT_BRANCH" --json | jq -r '.build_id')
until mecca build status "$BUILD_ID" -e dev --json \
| jq -e '.status | test("SUCCEEDED|FAILED|STOPPED")' >/dev/null; do
sleep 15
done
mecca build status "$BUILD_ID" -e dev --json | jq -e '.status == "SUCCEEDED"'
Troubleshooting Builds¶
Build fails with "repository not found"¶
Your Git credentials are not set up correctly. Check which authentication method you are using:
- OAuth users: Check your login status:
appmecca git-auth status - SSH deploy key users: Check the key exists:
appmecca git-auth status -e dev - Verify the deploy key (SSH) or OAuth token has access to the repository
- SSH requires the SSH URL format:
git@github.com:org/repo.git(not HTTPS). HTTPS URLs work with OAuth authentication.
Build fails during Docker build¶
Read the logs to see the error:
Common causes:
- Missing files in the Docker build context (check your
contextsetting inappmecca.yaml) - Package installation failures (network issues, missing system dependencies)
- Incorrect Dockerfile syntax
Build succeeds but image is wrong¶
Check that your appmecca.yaml points to the right Dockerfile and context. See Containers Configuration for all the options.
Next Steps¶
- Multi-Container Builds — Building multiple images from one repository
- Deploying Your App — Deploy a built image
- Containers Configuration — All
containersoptions inappmecca.yaml