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

Configure sources from different Git providers:
# GitHub source
resource "kubiya_source" "github_source" {
  url    = "https://github.com/org/github-tools"
  runner = "kubiya-hosted"
  
  dynamic_config = jsonencode({
    branch = "main"
    auth   = "github-integration"
  })
}

# GitLab source
resource "kubiya_source" "gitlab_source" {
  url    = "https://gitlab.com/org/gitlab-tools"
  runner = "kubiya-hosted"
  
  dynamic_config = jsonencode({
    branch = "master"
    path   = "kubiya-tools/"
  })
}

# Bitbucket source
resource "kubiya_source" "bitbucket_source" {
  url    = "https://bitbucket.org/workspace/bitbucket-tools"
  runner = "kubiya-hosted"
  
  dynamic_config = jsonencode({
    branch = "main"
    tag    = "v1.5.0"
  })
}

# Agent with tools from multiple providers
resource "kubiya_agent" "multi_provider_agent" {
  name         = "multi-provider-agent"
  runner       = "kubiya-hosted"
  description  = "Agent with tools from multiple Git providers"
  instructions = "You have access to tools from GitHub, GitLab, and Bitbucket repositories."
  
  sources = [
    kubiya_source.github_source.id,
    kubiya_source.gitlab_source.id,
    kubiya_source.bitbucket_source.id
  ]
}
Organize sources by team or function:
locals {
  teams = {
    devops = {
      url         = "https://github.com/org/devops-tools"
      path        = "devops/"
      description = "DevOps automation tools"
    }
    security = {
      url         = "https://github.com/org/security-tools"
      path        = "security/"
      description = "Security scanning and compliance tools"
    }
    data = {
      url         = "https://github.com/org/data-tools"
      path        = "data-engineering/"
      description = "Data processing and analytics tools"
    }
  }
}

resource "kubiya_source" "team_sources" {
  for_each = local.teams
  
  url    = each.value.url
  runner = "kubiya-hosted"
  
  dynamic_config = jsonencode({
    path        = each.value.path
    branch      = "main"
    team        = each.key
    description = each.value.description
  })
}

# DevOps team agent
resource "kubiya_agent" "devops_agent" {
  name         = "devops-team-agent"
  runner       = "kubiya-hosted"
  description  = "DevOps team automation agent"
  instructions = "You are a DevOps agent with access to infrastructure and deployment tools."
  
  sources = [kubiya_source.team_sources["devops"].id]
  
  groups = ["DevOps", "SRE"]
}

# Security team agent
resource "kubiya_agent" "security_agent" {
  name         = "security-team-agent"
  runner       = "kubiya-hosted"
  description  = "Security team automation agent"
  instructions = "You are a security agent with access to scanning and compliance tools."
  
  sources = [kubiya_source.team_sources["security"].id]
  
  groups = ["Security", "Compliance"]
}

​
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

  • Verify the repository URL is correct and accessible
  • Check authentication configuration for private repositories
  • Ensure the Kubiya service has network access to the Git provider
  • Validate credentials and permissions for the repository
  • Check that tool definitions follow the correct schema
  • Verify file paths and directory structure in the repository
  • Review dynamic_config path settings for accuracy
  • Ensure tool files have proper YAML syntax
  • Verify that specified branches or tags exist in the repository
  • Check for typos in branch/tag names (case-sensitive)
  • Ensure the branch/tag contains the expected tool files
  • Review Git provider permissions for tag/branch access