The kubiya_source resource allows you to connect Git repositories containing tools and workflows to the Kubiya platform. These repositories provide agents with the functionality needed to perform tasks. For inline tool and workflow definitions, use the kubiya_inline_source resource instead.
Sources are the foundation for extending agent capabilities. They allow you to version control your tools and workflows while making them available across your organization.

​
Prerequisites

Before using this resource, ensure you have:
  1. A Kubiya account with API access
  2. An API key (generated from Kubiya dashboard under Admin → Kubiya API Keys)
  3. A Git repository containing tools and workflows (public or with appropriate credentials)
  4. The repository URL accessible from your Kubiya environment

​
Quick Start

resource "kubiya_source" "github_tools" {
  name        = "community-tools"
  description = "Kubiya community tools repository"
  url         = "https://github.com/kubiyabot/community-tools"
  runner      = "kubiya-hosted"
}

resource "kubiya_agent" "basic_agent" {
  name         = "basic-agent"
  runner       = "kubiya-hosted"
  description  = "Agent with community tools"
  instructions = "You are an agent with access to community tools."
  
  sources = [kubiya_source.github_tools.id]
}

​
Configuration Examples

Create environment-specific sources for different deployment stages:
locals {
  environments = {
    dev = {
      url    = "https://github.com/org/dev-tools"
      branch = "develop"
    }
    staging = {
      url    = "https://github.com/org/staging-tools"
      branch = "staging"
    }
    prod = {
      url    = "https://github.com/org/prod-tools"
      branch = "main"
    }
  }
}

resource "kubiya_source" "env_sources" {
  for_each = local.environments
  
  url    = each.value.url
  runner = "kubiya-hosted"
  
  dynamic_config = jsonencode({
    environment = each.key
    branch      = each.value.branch
    restricted  = each.key == "prod" ? true : false
  })
}

resource "kubiya_agent" "env_agents" {
  for_each = local.environments
  
  name         = "${each.key}-agent"
  runner       = "kubiya-hosted"
  description  = "Agent for ${each.key} environment"
  instructions = "You manage the ${each.key} environment with appropriate tools."
  
  sources = [kubiya_source.env_sources[each.key].id]
  
  environment_variables = {
    ENVIRONMENT = each.key
  }
}

​
Advanced Configurations

​
Arguments Reference

​
Required Arguments

​
url
string
required
URL to a Git repository containing tools and workflows. Supports HTTP/HTTPS URLs for public and private repositories.

​
Optional Arguments

​
runner
string
default:"kubiya-hosted"
The runner to use for executing tools from this source. Use “kubiya-hosted” for cloud execution or specify your custom runner.
​
dynamic_config
string
JSON-encoded configuration for the source. Common options include:
  • branch - Git branch to use (e.g., “main”, “develop”)
  • tag - Git tag to use for version pinning (e.g., “v1.2.0”)
  • path - Subdirectory within the repository containing tools
  • auth - Authentication method for private repositories
  • environment - Environment identifier for organization

​
Attributes Reference

In addition to all arguments above, the following attributes are exported:
​
id
string
The unique identifier of the source.
​
name
string
The computed name of the source (derived from repository name).

​
Repository Structure

Your Git repository should follow these conventions for tools and workflows: 
repository/
├── tools/
│   ├── tool1/
│   │   ├── tool.yaml      # Tool definition
│   │   └── scripts/       # Tool scripts
│   ├── tool2/
│   │   ├── tool.yaml
│   │   └── Dockerfile     # Custom container
│   └── shared/
│       └── common.sh      # Shared utilities
├── workflows/
│   ├── workflow1.yaml     # Workflow definitions
│   └── workflow2.yaml
└── README.md             # Documentation

​
Import

Sources can be imported using their ID: 
terraform import kubiya_source.example <source-id>

​
Best Practices

Version Control

  • Use specific branches or tags for production deployments
  • Implement proper Git branching strategy (main, develop, feature branches)
  • Tag releases with semantic versioning (v1.2.3)
  • Use different branches for different environments

Repository Organization

  • Organize tools logically within your repository structure
  • Use clear naming conventions for tools and workflows
  • Include comprehensive README files and documentation
  • Group related tools in subdirectories by function or team

Security

  • Use private repositories for proprietary or sensitive tools
  • Configure appropriate Git credentials via Kubiya integrations
  • Implement access controls and code review processes
  • Audit tool usage and repository access regularly

Testing & Deployment

  • Test repository connections in development environments first
  • Validate tool definitions before committing to main branches
  • Implement CI/CD pipelines for tool repositories
  • Monitor source health and tool execution success rates

​
Dynamic Configuration Options

{
  "branch": "main",
  "tag": "v1.2.0",
  "path": "tools/production"
}

​
Compatibility

Requirements:
  • Kubiya Terraform Provider version >= 1.0.0
  • Terraform >= 1.0
  • Git repositories must be accessible (public or with appropriate credentials)
  • Sources must be created before agents can reference them
Supported Providers:
  • GitHub (github.com)
  • GitLab (gitlab.com and self-hosted)
  • Bitbucket (bitbucket.org)
  • Azure DevOps
  • Other Git providers accessible via HTTP/HTTPS
Important Considerations:
  • Repository URLs must be accessible from the Kubiya environment
  • Private repositories require proper authentication setup
  • Tool definitions must follow Kubiya schema specifications
  • Large repositories may impact source loading times

​
Troubleshooting