LogoFreestyle

Overview

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}`);
  });

The action currently only supports webhooks.

The webhook payload includes the following fields:

interface GitTriggerPayload {
  repoId: string;
  // The name of the branch that was updated
  branch: string;
  // The SHA of the commit that triggered the webhook
  commit: string;
}

Local Development

For local development, you can use a tool like tailscale to create a secure tunnel to your localhost, allowing your webhook to receive events from Freestyle.

You can setup Tailscale by following the quickstart guide here.

To set up a tunnel once you have tailscale installed, you can use the following command (Replace 3000 with the port your server is listening on):

tailscale funnel 3000

This exposes your server to the public internet on a url given to you by Tailscale.

The output should look like this:

Available on the internet:

https://<device name>.<tailnet id/name>.ts.net/
|-- proxy http://127.0.0.1:3000

Press Ctrl+C to exit.

Use the provided url as the webhook URL in your trigger configuration.

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://x-access-token:your-token@git.freestyle.sh" >> ~/.git-credentials

For non-standard Git clients that only provide an access token field, just use the token.

The username is your identity ID, and the password is your access token. The access token ID is only used for revoking the token and isn't needed here.

Don't do this on a shared machine, as it will set your git credentials globally. To do this locally, you can use the --local flag with git config.

Continuous Integration Example

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

  1. 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}`);
  1. Grant the identity write access to your repository:
await sandboxes.grantPermission({
  identityId: ciIdentity.id,
  repoId: "repo-id",
  permission: "write",
});
  1. 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",
  },
});
  1. 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}`);
  });

Git Objects API

Freestyle provides a Git Objects API that allows you to access and explore Git objects directly from your repositories. This API is useful for building tools that need to understand Git repository structure, inspect files, visualize commit history, and more.

For a detailed guide on working with Git objects, check out our Git Objects API Guide.

GitHub Synchronization

Freestyle provides seamless bidirectional synchronization between your Freestyle repositories and GitHub repositories. This integration allows you to maintain synchronized code across both platforms while leveraging Freestyle's infrastructure.

For complete setup instructions and usage details, see our GitHub Sync Guide.

API Reference

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

Best Practices

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

Building an AI Mobile App Builder

Shipping AI driven mobile apps with Freestyle

GitHub Synchronization

Seamlessly sync your Freestyle repositories with GitHub using bidirectional synchronization