Learn how to use Freestyle's Git API to manage and deploy code from Git repositories

Git with Freestyle

Freestyle provides a comprehensive Git API that enables you to manage Git repositories, control access permissions, and set up automation triggers. This document covers everything you need to know about using Git with Freestyle.

Overview

Freestyle's Git support allows you to:

Create and manage Git repositories
Control repository access with identity-based permissions
Set up automation triggers for repository events
Integrate with CI/CD workflows
Deploy applications directly from Git

Git Repositories

Creating a Repository

To create a new Git repository:

import { FreestyleSandboxes } from "freestyle-sandboxes";
 
const sandboxes = new FreestyleSandboxes({
  apiKey: "your-api-key",
});
 
// Create a basic repository
sandboxes
  .createGitRepository({
    name: "example-repo",
  })
  .then((res) => {
    console.log(res.repoId);
  });

Note that the name of the repository is optional and is for display purposes only. The actual repository ID is generated by Freestyle.

Create a public repository:

sandboxes
  .createGitRepository({
    name: "public-example",
    public: true,
  })
  .then((res) => {
    console.log(res.repoId);
  });

Create a repository from an existing Git repository

sandboxes.createGitRepository({
  name: 'cloned-example',
  source: {
    type: 'git',
    url: 'https://github.com/freestyle-sh/cloudstate',
    branch: 'main' // Optional: specify branch to checkout
    depth: 0, // Optional: shallow clone
  }
}).then(res => {
  console.log(res.repoId);
});

Note that there is currently no support for private repositories from outside of Freestyle.

After creating a repository, you can push code to it using the standard Git CLI:

# Add the repository as a remote
git remote add freestyle https://git.freestyle.sh/your-repo-id
 
# Push your code
git push freestyle main

Listing Repositories

You can list all repositories associated with your account:

sandboxes.listGitRepositories().then((repos) => {
  console.log(repos);
});

Deleting Repositories

When you no longer need a repository, you can delete it:

sandboxes
  .deleteGitRepository({
    repoId: "repo-id",
  })
  .then(() => {
    console.log("Repository deleted");
  });

Identity and Access Management

Freestyle uses identity-based access control for Git repositories. This allows you to create separate identities for different purposes (e.g., CI/CD, team members) and grant them specific permissions.

Creating an Identity

sandboxes.createGitIdentity().then((identity) => {
  console.log(identity.id);
});

Managing Access Tokens

Each identity can have one or more access tokens used for authentication:

// Create a token for an identity
sandboxes
  .createGitToken({
    identityId: "identity-id",
  })
  .then((token) => {
    console.log(token.value); // Store this securely
  });
 
// List tokens for an identity
sandboxes
  .listGitTokens({
    identityId: "identity-id",
  })
  .then((tokens) => {
    console.log(tokens);
  });
 
// Revoke a token
sandboxes
  .revokeGitToken({
    identityId: "identity-id",
    tokenId: "token-id",
  })
  .then(() => {
    console.log("Token revoked");
  });

Managing Permissions

You can grant identities different levels of access to your repositories:

// Grant read-only access
sandboxes
  .grantPermission({
    identityId: "identity-id",
    repoId: "repo-id",
    permission: "read",
  })
  .then(() => {
    console.log("Read access granted");
  });
 
// Grant read-write access
sandboxes
  .grantPermission({
    identityId: "identity-id",
    repoId: "repo-id",
    permission: "write",
  })
  .then(() => {
    console.log("Write access granted");
  });
 
// List permissions for an identity
sandboxes
  .listPermissions({
    identityId: "identity-id",
  })
  .then((permissions) => {
    console.log(permissions);
  });
 
// Revoke access
sandboxes
  .revokePermission({
    identityId: "identity-id",
    repoId: "repo-id",
  })
  .then(() => {
    console.log("Access revoked");
  });

Git Triggers

Git triggers allow you to automate actions when certain events occur in your repositories, such as a push to a specific branch.

Creating a Trigger

// Create a webhook trigger for all pushes to the main branch
sandboxes
  .createGitTrigger({
    repoId: "repo-id",
    trigger: {
      event: "push",
      branch: ["main"], // Optional: filter by branch
      fileGlob: ["*.js"], // Optional: filter by file patterns
    },
    action: {
      type: "webhook",
      url: "https://your-webhook-url.com",
    },
  })
  .then((result) => {
    console.log(`Trigger created: ${result.triggerId}`);
  });

Listing Triggers

sandboxes
  .listGitTriggers({
    repoId: "repo-id",
  })
  .then((triggers) => {
    console.log(triggers);
  });

Deleting Triggers

sandboxes
  .deleteGitTrigger({
    repoId: "repo-id",
    triggerId: "trigger-id",
  })
  .then(() => {
    console.log("Trigger deleted");
  });

Authentication for Git Operations

To authenticate Git CLI operations with Freestyle, you'll need to configure Git to use your access token:

# Set up credential helper for freestyle domains
git config --global credential.helper store
echo "https://your-username:your-token@git.freestyle.sh" >> ~/.git-credentials

Alternatively, you can use SSH keys for authentication, which is recommended for automated systems and continuous integration.

Continuous Integration Example

Here's an example of how to set up a CI workflow with Freestyle Git:

Create a dedicated Git identity for CI:

const ciIdentity = await sandboxes.createGitIdentity();
const token = await sandboxes.createGitToken({
  identityId: ciIdentity.id,
});
console.log(`CI token: ${token.value}`);

Grant the identity write access to your repository:

await sandboxes.grantPermission({
  identityId: ciIdentity.id,
  repoId: "repo-id",
  permission: "write",
});

Set up a webhook trigger to notify your CI system:

await sandboxes.createGitTrigger({
  repoId: "repo-id",
  trigger: {
    event: "push",
    branch: ["main"],
  },
  action: {
    type: "webhook",
    url: "https://your-ci-system.com/webhook",
  },
});

Configure your CI system to clone the repository, run tests, and deploy if successful.

Deployment with Git

Freestyle makes it easy to deploy applications directly from Git repositories:

// TODO: This is not yet implemented
// Deploy a web application from a Git repository
const yourRepoId = "your-repo-id";
 
sandboxes
  .deployWeb({
    source: {
      type: "git",
      url: `https://git.freestyle.sh/${yourRepoId}`,
      branch: "main", // Optional: defaults to main
    },
    {
      entrypoint: "index.js", // Optional: defaults to index.js
      domains: ["example.style.dev"], // Optional: specify domains
      build: true // automatically detect your framework and build for you
    }
  })
  .then((deployment) => {
    console.log(`Deployed to: ${deployment.url}`);
  });

API Reference

For complete details on all available Git API endpoints, refer to the API Reference section.

Best Practices

Use dedicated identities for different purposes (CI/CD, team members, etc.)
Regularly rotate access tokens for security
Limit permissions to the minimum required access level
Use webhooks to integrate with your existing CI/CD workflows
Secure sensitive variables using environment variables rather than committing them to your repository

Using Git with Freestyle