THE VASADEPLOY GUIDE

From repository
to ready to ship.

Connect your code, define a workflow, and build on a cloud runner. Everything you need to get your first build running lives here.

Start with your first build →

01 / START HERE

Getting started

VasaDeploy runs your repository’s build commands and collects the files you want to download.

Sign in and choose your Personal account or an organization.
Connect GitHub through Integrations and grant access to the repository you want to build.
Commit a vdeploy.yaml file at the repository root. Use the example below as a starting point.
Create a project, select the repository, branch, and workflow, then start a build.
Open the build to follow its logs and download the resulting artifacts.

For a Flutter app at the repository root, use working_directory: .. For a monorepo, use the directory containing that app’s pubspec.yaml.

Projects & repositories

A project connects a repository to its build settings. Choose the branch and a workflow defined in vdeploy.yaml. Keep that file in version control so changes to build commands can be reviewed alongside your code.

Check the selected account before creating a project: Personal and organization accounts have separate projects, integrations, and credit balances.

02 / BUILD

Workflow configuration

Create vdeploy.yaml at your repository root. Each entry under workflows names a build you can select in VasaDeploy.

vdeploy.yaml Flutter · Android

workflows:
  android-debug:
    runner: linux
    working_directory: apps/flutter
    steps:
      - name: Install dependencies
        run: flutter pub get
      - name: Build APK
        run: flutter build apk --debug
    artifacts:
      - build/app/outputs/flutter-apk/app-debug.apk

Core workflow fields
Field	Purpose
`runner`	Select `linux` or `windows`.
`working_directory`	Directory in the repository where build commands run.
`steps`	Ordered commands, each with a descriptive `name` and a `run` command.
`artifacts`	Output paths to upload, relative to the working directory.
`environment.vars`	Non-secret environment variables for the workflow.
`secrets`	Names of stored secrets the build needs.

Use separate workflows for debug and release builds, or for different platforms. A failing command stops the build; inspect that step’s logs before rerunning.

Runners & platforms

A runner is the machine that executes your workflow.

Linux: Android and Linux builds. Flutter/Android workflows can use the prepared build toolchain.
Windows: Windows builds using PowerShell 7. Requires paid credits and JIT runner mode. Package the complete application directory, including its DLLs and data.
macOS / iOS: Planned. Mac runner provisioning is not available yet.

Build machines can be interrupted. If a Spot interruption fails a build, rerun explicitly after checking any publishing side effects.

Secrets & environment

Store credentials in VasaDeploy’s Secrets settings and reference their names in your workflow. Use project secrets when a credential belongs to one project. Keep ordinary configuration in environment.vars.

Keep tokens, passwords, signing credentials, and private keys out of your repository and YAML. Avoid printing credentials in build commands or logs.

Dependency caching

Enable the project Cache setting to reuse dependencies across builds. Flutter/Android defaults include hosted Pub packages, Gradle dependencies, and Gradle wrapper distributions.

Use cache.paths only when you need to override the defaults. Supported Linux paths include ~/.pub-cache/hosted, ~/.pub-cache/git, ~/.gradle/caches, and ~/.gradle/wrapper/dists. Windows supports $PUB_CACHE/hosted and $PUB_CACHE/git.

Individual cache archives over 2 GiB are skipped.
Each project has a 5 GiB cache cap, with least-recently-restored entries evicted first.
Entries not restored for 14 days expire.

Cache dependencies, not build output. Do not cache build/, .dart_tool, or an entire Gradle home.

Logs & artifacts

Open a build to follow step progress and logs. Declare the files you want to keep under artifacts, then download them from the build detail page once uploaded.

Artifact paths are relative to working_directory. If a file is missing, check the build command’s output location and whether the packaging step completed. For Windows, upload a ZIP of the complete app directory rather than just its executable.

03 / MANAGE & SHIP

Free builds & credits

Personal accounts include 3 free builds per day and 30 per month for Android and Linux. Each free build has a 20-minute machine limit, including setup and artifact upload; queue time is excluded. Unused allowances do not carry forward.

A manual retry uses a new allowance. Use prepaid credits for paid builds, including Windows. Purchased credits do not expire; Personal and organization balances are separate.

Check your balance and payment history in Billing for the account that owns the project.

Organizations & access

Create an organization to share projects with your team. Use the account switcher to move between Personal and organization workspaces.

Owners and admins manage organization settings and sensitive integrations. Billing is managed by the account owner. Assign team roles according to the access each member needs.

Google Play publishing

Save your account connection in Integrations, then reference its name in your project's vdeploy.yaml. The AAB path must also be declared explicitly in artifacts.

publishing:
  google_play:
    integration: vasasu-global
    package_name: com.example.app
    track: internal
    artifact: build/app/outputs/bundle/release/app-release.aab
    submit_as_draft: true

Publishing starts after the build passes. Follow upload and release progress on the build page. The connection's key stays in the backend.

Microsoft Store publishing

Owners and admins can connect Microsoft Partner Center in Integrations, then configure a project’s Store destination. Store packages must be declared in artifacts; the workflow must explicitly opt in with publishing.partner_center: {}.

Saving a destination alone does not publish a build. Publishing starts after a successful build and artifact upload, and its progress is tracked separately. Microsoft credentials stay in the backend rather than being injected into the build runner.

A successful build does not mean Microsoft has certified or released the submission. Check the publishing status and Partner Center before submitting again.

Troubleshooting

Repository or workflow missing: Check GitHub repository access, the selected branch, and that vdeploy.yaml is committed at the repository root.
Build fails at dependency installation: Read the first failing step. Verify the working directory, required tool versions, and credentials for private dependencies.
No downloadable artifact: Confirm the output exists and its path matches artifacts relative to the working directory.
Free build hits its time limit: Enable dependency caching or choose a paid build. Setup and upload time count toward the free limit.
Cannot manage billing or integrations: Check the selected workspace and your role. Ask the owner or an admin to make changes requiring their access.

From repositoryto ready to ship.