Skip to main content

Git Integration

Swisblade deploys code directly from your Git repositories. Both GitHub and GitLab are supported.

Repository URL format​

Use the full clone URL in your stack.json:

"source": {
  "repo": "github.com/your-org/your-repo.git",
  "ref": "main"
}

For GitLab:

"source": {
  "repo": "gitlab.com/your-org/your-repo.git",
  "ref": "main"
}
tip

Both github.com/you/repo.git and https://github.com/you/repo.git are accepted — the protocol prefix is normalized automatically.

Personal Access Tokens​

If your repository is private, you need to provide a Personal Access Token (PAT) when creating the project. The PAT is used to clone and pull your code.

GitHub PAT​

  1. Go to GitHub → Settings → Developer settings → Personal access tokens → Fine-grained tokens
  2. Click Generate new token
  3. Set a descriptive name (e.g., swisblade-deploy)
  4. Select the repositories you want Swisblade to access
  5. Under Permissions → Repository permissions, grant Contents: Read-only
  6. Click Generate token and copy it

GitLab PAT​

  1. Go to GitLab → Preferences → Access Tokens
  2. Click Add new token
  3. Set a name (e.g., swisblade-deploy)
  4. Select the read_repository scope
  5. Click Create personal access token and copy it

How PATs are stored​

  • Your PAT is encrypted (AES-256-GCM) before being stored. It is never visible in plain text after saving.
  • The encryption key lives on the server — it never reaches the browser.
  • You can replace a PAT at any time from Project Settings, but you cannot reveal the existing one.
  • Clone error messages sanitize the URL so your token is never exposed in logs.
caution

Swisblade only needs read access to your repositories. Never grant write permissions to the PAT.

Multi-repo projects​

Each service can come from a different repository:

{
  "name": "my-platform",
  "services": {
    "api": {
      "source": { "repo": "github.com/myorg/api.git", "ref": "v2.1.0" },
      "type": "app",
      "runtime": "node",
      "port": 3000
    },
    "worker": {
      "source": { "repo": "github.com/myorg/worker.git", "ref": "v1.3.0" },
      "type": "app",
      "runtime": "python",
      "port": 8080
    }
  }
}

All repos are cloned using the same PAT. If your services span multiple GitHub/GitLab organizations, make sure the PAT has access to all of them.

Syncing on redeploy​

When you trigger a redeploy:

  1. Swisblade runs git fetch + git checkout on each service's repository
  2. If the ref is a branch, it pulls the latest commit
  3. If the ref is a tag or SHA, it checks out that exact version
  4. Changed files trigger a Docker image rebuild

This means:

  • Branches ("main", "develop") → always deploy the latest code
  • Tags ("v1.2.0") → deploy the same version every time
  • SHAs ("a1b2c3d") → deploy an exact, immutable snapshot

Updating the stack contract​

If you change your stack.json between deploys, Swisblade detects the diff and:

  • Provisions new infrastructure if you added needs
  • Allocates new ports for new services
  • Cleans up port allocations for removed services

You can also edit stack.json directly from Project Settings → Stack Contract in the dashboard.