# Venue.sh Documentation > Venue.sh Documentation This file contains all documentation content in a single document following the llmstxt.org standard. ## Activity Log The Activity Log records user-generated events in Venue.sh, making it easy to see what changes were made, when they occurred, and who made them. This feature provides organization admins with valuable transparency and accountability for audit and security purposes. Tracked event types include plugin connections, configuration changes, user logins, permission updates, and more. ![Activity Log](./assets/activity-log.png) ## Search and Filter Options Use the activity table to browse all logged events. To find specific events, users, or actions, use the search feature. For quick troubleshooting and system analysis, the **Status** and **Risk** filters are especially useful. ### Date Range Use the date picker to focus activity logs to a specific date range. ## Data Export Users can export the contents of the activity table as a CSV or JSON file. This allows for deeper analysis or long-term archiving of event logs outside the Venue.sh portal, supporting data-driven decisions and recordkeeping. :::note - The standard retention of logged activity is three years. Reach out to the Venue.sh team if you need activity retained for a longer period of time. - Exported files are currently bulk exports, meaning the files will contain more info than you see in Venue.sh. From that bulk export, you can filter and search using your preferred spreadsheet tool. ::: --- ## Agents Agents in Venue.sh let your organization define purpose-built AI agents with custom instructions, example prompts, and capability bindings. Each agent can be selected from the Venue.sh Assistant to handle specific workflows - from answering questions about your catalog to performing tool-assisted tasks across your engineering platform. ## Key Capabilities - **Organization registry** - Browse and search all agents configured for your organization. - **Custom instructions** - Define what an agent does and how it should respond, in plain natural language. - **Capability bindings** - Grant agents access to Venue tools, MCP server tools, and other agents. - **Templates** - Start from a predefined template to get up and running quickly. - **Safety controls** - Require human approval before an agent executes sensitive actions. - **Lifecycle management** - Move agents through Draft, Ready, Disabled, and Archived states. ## Browsing Agents 1. Open _Agents_ from the sidebar (under _AI_). 2. Use the search box to filter by name. 3. Use the **Status** filter to narrow by agent state. 4. Click an agent name to open its detail page. The list shows each agent's name, description, status, capability summary, creator, and timestamps. ## Creating an Agent Admins and Editors can create agents. Contributors, Viewers, and Demo users can browse agents but cannot add or edit them. 1. Go to _Agents_ and click **Create agent**. 2. **OPTIONAL:** Select a template to pre-fill the name, description, instructions, and example prompts. 3. Enter a **Name** for the agent. 4. Enter a **Description** summarizing the agent's purpose. 5. Enter **Instructions** - write what this agent does and how it should respond. Instructions are sent to the AI model as the system prompt for every conversation that uses this agent. 6. **OPTIONAL:** Add **Example prompts** - short phrases that guide users on how to interact with the agent. Type a prompt and click **Add** (or press Enter) to include it. 7. **OPTIONAL:** Enable **Require approval for sensitive actions** to have the agent pause and wait for a human decision before executing actions flagged as sensitive. 8. **OPTIONAL:** Open **Capability bindings** to select the tools this agent may use (see [Capability Bindings](#capability-bindings) below). 9. Click **Create agent**. Venue.sh creates the agent in _Draft_ status and opens its detail page. ## Capability Bindings Capability bindings control which tools and sub-agents an agent can invoke at runtime. Three types are available: - **Venue tools** - Built-in Venue.sh tools such as catalog search, entity lookup, and other platform features. - **MCP tools** - Individual tools from your organization's registered [MCP servers](./mcp-servers.md). Tools are grouped by server. Use **Add all** to bind every tool from a server at once, or select individual tools with the checkboxes. - **Agents** - Other agents in your organization. Binding an agent as a capability allows this agent to delegate specific tasks to it during a conversation. A summary of all selected tools appears at the top of the picker and can be expanded to review or remove individual bindings. Capability bindings can be configured at creation time or updated later by editing the agent. ## Viewing Agent Details The detail page shows: - **Name and status** - The agent name with a status chip indicating its current lifecycle state. - **Metadata** - Creator and last updated timestamp. - **Instructions** - The system prompt the agent uses. - **Example prompts** - Suggested phrases for users, if configured. - **Capability bindings** - All tools and sub-agents bound to this agent, filterable by type (All, Venue tools, MCP tools, Agents). Each binding card shows the tool name, type, source server (for MCP tools), and whether the binding requires approval. ## Agent Lifecycle Agents move through the following states: | Status | Meaning | | --------------- | ------------------------------------------------------------- | | Draft | Newly created; not yet available for use in conversations. | | Ready | Active and available for selection in the Assistant. | | Needs attention | One or more capability bindings are degraded or disconnected. | | Disabled | Temporarily unavailable for new conversations. | | Archived | Permanently retired; no longer available for selection. | The following actions are available from the agent detail page: - **Mark as ready** - Make a Draft or Needs attention agent available for use in the Assistant. - **Duplicate** - Create a copy of the agent with the same name, instructions, and capability bindings. - **Disable agent** - Prevent the agent from being selected for new conversations. Restore it later with **Restore**. - **Restore** - Re-enable a Disabled agent by setting it back to Ready. - **Archive agent** - Permanently retire the agent. Archived agents cannot be restored. ## Example Agents Here are some example agents that you could build. ### Atlassian Agent This is an example of an agent that can be created to help you interact with Atlassian products such as Jira, Confluence, and Bitbucket. - Have a repository imported that is imported from a [Bitbucket connection](./../connections/git/) linked to a Jira project and Confluence space - Add the Atlassian Rovo MCP Sever to the dashboard via the [MCP Servers](./mcp-servers.md) - Information about how to use the API token to access the Atlassian Rovo MCP server can be found [here](https://support.atlassian.com/atlassian-rovo-mcp-server/docs/authentication-and-authorization/) - At the time of writing (July 2026), the Atlassian Rovo MCP server exposes around 45 tools - Create an agent with the following instructions: - Name and description: Atlassian Agent - Instructions: - ```markdown You are an expert assistant for Atlassian products (Jira, Confluence, and Bitbucket) within this organization. Use the available tools to answer questions and perform actions: - Use the catalog-search, catalog-entity, repo-search, and repo-summary tools to find the repository or component the user is asking about, and to identify its linked Jira project - Use the jira tool for quick lookups of issues, projects, and sprints already associated with the repository in the Venue catalog - Use the Atlassian Rovo MCP tools for anything the jira tool cannot answer, such as issue details, comments, worklogs, sprint reports, Confluence pages, and Bitbucket pull requests When responding: - Confirm which Jira project or repository you are referencing before giving a status update - Summarize sprint, issue, or pull request status in plain language: what is done, what is in progress, and what is blocked - Include issue keys and links when available so the user can jump directly to Jira or Confluence - Before creating, updating, or transitioning a Jira issue, confirm the target issue and the intended change with the user - If you cannot find a linked Jira project or repository for a request, say so and ask the user to confirm the project key or repository name ``` - Example prompts: - "How is the express-api project doing?" - "What is the status of the Sprint 12?" - Capability bindings: - Venue tools: - catalog-search - catalog-entity - jira - repo-search - repo-summary - MCP tools: - Look for the Atlassian Rovo MCP server that was added to the dashboard. For example: - atlassianUserInfo - getJiraIssue - Other tools of interest that are available to your Atlassian Rovo MCP server ### DevOps Agent This is an example of an agent that can be created to help you troubleshoot Helm-based services and their live state in Kubernetes. - Have Helm-based repositories imported into the catalog so the agent can find each service's chart, values, and repository - Add a Kubernetes MCP server to the dashboard via the [MCP Servers](./mcp-servers.md), such as [kubectl-mcp-server](https://github.com/rohitg00/kubectl-mcp-server) - kubectl-mcp-server exposes tools for pods, deployments, logs, events, and Helm releases, plus higher-level diagnostics such as `diagnose_pod_crash` and `compare_namespaces` - Configure the server with read-only or non-destructive mode (_e.g.,_ `--read-only` or `--disable-destructive`) if you want the agent limited to investigation rather than making changes to the cluster - Create an agent with the following instructions: - Name and description: DevOps Agent - Instructions: - ```markdown You are an expert in Kubernetes and Helm, helping engineers understand and troubleshoot the services running in this organization's clusters. Use the available tools to answer questions and perform actions: - Use the catalog-search, catalog-entity, repo-search, and repo-summary tools to find the repository or component the user is asking about, and to identify its Helm chart, values, and target namespace. - Use the Kubernetes MCP tools to inspect live cluster state, such as pods, deployments, logs, events, and Helm releases. - Prefer read-only tools (get_pods, get_logs, get_pod_events, helm_status, helm_get_values, kubectl_describe) before suggesting or taking any action that changes cluster state. When responding: - Confirm which service, namespace, and cluster context you are referencing before giving a status update. - When troubleshooting, walk through the diagnosis: what you checked, what you found, and the likely root cause, before recommending a fix. - Reference the Helm release and chart values when a service's configuration is relevant to the issue. - Before running any command that changes cluster or Helm state (_e.g.,_ scaling, rolling back, or upgrading a release), confirm the target and the intended change with the user. - If you cannot find a catalog entity or Helm release for a request, say so and ask the user to confirm the service name, namespace, or cluster context. ``` - Example prompts: - "Why is the payments-api pod crashing in staging?" - "Show me the Helm values for the checkout-service release in production." - Capability bindings: - Venue tools: - catalog-search - catalog-entity - repo-search - repo-summary - MCP tools: - Look for the Kubernetes MCP server that was added to the dashboard. For example: - get_pods - get_logs - diagnose_pod_crash - helm_status - helm_get_values - Other tools of interest that are available to your Kubernetes MCP server ## Useful Things to Ask About The Assistant can answer questions about your organization's agents. For example: - "What agents are available in our organization?" - "Summarize the available agents" - "Which agents have access to Jira tools?" ## Permissions | Role | Permissions | | ------------------------- | -------------------------------- | | Admin, Editor | Create, Read, Update, and Delete | | Contributor, Viewer, Demo | Read only | Create, update, and delete actions on agents are recorded in the [Activity Log](../activity-log.md). ## Troubleshooting | Situation | What to do | | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Agent is not selectable in the Assistant | The agent may be in Draft, Disabled, or Archived status. Open _Agents_, find the agent, and click **Mark as ready** from the detail page. | | Capability binding shows Needs attention | A bound MCP server or tool may have been removed or become unreachable. Open the agent, review the capability bindings, and remove or replace the affected binding. | | Cannot see the **Create agent** button | Your role may not include Agents create permission. Contact your Venue administrator. | | An archived agent needs to be recovered | Archived agents cannot be restored. Use **Duplicate** on a similar agent, or create a new agent with the same configuration. | | Agent requires approval unexpectedly | The agent was created with **Require approval for sensitive actions** enabled. Edit the agent and toggle the setting off if approval is no longer needed. | ## See Also - [Assistant](./assistant.md) - Using the Assistant in the Venue.sh portal. - [MCP Servers](./mcp-servers.md) - Register and inspect MCP servers whose tools you can bind to agents. - [Skills](./skills.md) - Browse agent skills auto-discovered from connected repositories. - [Activity Log](../activity-log.md) - Audit trail for configuration changes. --- ## Assistant The Assistant feature brings generative AI capabilities to your Venue.sh experience in a few key ways: - It embeds validated AI models into the Venue.sh portal. - The Assistant grants the AI permission to safely and securely retrieve user and your organization's catalog information from your Venue instance. - It intelligently interprets your goals and uses the most relevant capabilities to assist you. - The Assistant can be prompted with casual, natural language. ## Key Capabilities Use the Assistant to intelligently search and discover information and complete tasks within your Venue instance related to: - **Software catalog** - Search and view entities such as APIs, Components, Groups, Locations, Rules, Templates, and Users - **Technical documentation** - Search and read TechDocs - **Templates** - Generate and validate YAML templates for scaffolding new entities - **Plugin integrations** - Retrieve data from enabled integrations (see [Supported Plugins](#supported-plugins) below) - **MCP Servers** - List registered MCP servers and inspect their tools, resources, and prompts (see [MCP Servers](./mcp-servers.md)) - **Skills** - Discover agent skills cataloged from your connected Git repositories (see [Skills](./skills.md)) - **Repository intelligence** - Summarize and search ingested repository content when ingestion is enabled (see [Ingestion & Summary](../developer-portal/ingestion-and-summary.md)) The Assistant will suggest follow-up questions after each response to help you refine your conversation. You can switch AI models at any time (but it is best not to switch part way through a conversation) and your conversation history is saved so you can return to it later. ## Using the Assistant Here are some ideas to consider as you get started with the Venue.sh Assistant. - **Start a Conversation** - Open the Assistant from the sidebar and type your question or request. You can ask about catalog entities, documentation, templates, or any enabled plugin data. Be as specific as you like as the Assistant will use your intent to fetch the right information. - **Choose an AI Model** - You can select which AI model to use from the model dropdown at the start of a conversation. The list of available models depends on how your Venue administrator has configured the Assistant. With multiple models available, you can start a new conversation with a different model anytime. Supported providers include OpenAI, Anthropic, Google (Gemini) and Anthropic models from AWS Bedrock. If you don't see the model you want, ask your administrator to add it in Assistant settings. The Venue.sh team is also working to add additional providers. - **Follow-up Suggestions** - After the Assistant replies, you'll see a few suggested follow-up questions. Click any suggestion to send it as your next message. Use these to go deeper on a topic or explore related questions without typing. - **Conversation History** - Past conversations are saved. Use the history panel to search, open, or delete conversations. You can delete a single conversation or clear all history when you no longer need it. ### Useful Things to Ask About - **Software Catalog** - The Assistant can search and retrieve details about entities in your software catalog, including APIs, Components, Groups, Locations, Rules, Templates, and Users. Example prompts: - "Find all APIs owned by Team Platform" - "Show me the details of the payments-service component" - "List all components with lifecycle production" - "What groups exist in my organization?" - **Technical Documentation (TechDocs)** - Search and read technical documentation published in your Venue instance. Ask for specific topics or documents by name or subject. Example prompts: - "Search TechDocs for authentication setup" - "Show me the deployment guide for the checkout service" - "What documentation exists for our API standards?" - **Template Generation and Validation** - You can ask the Assistant to generate the YAML file needed to scaffold new entities in your Venue instance or to validate existing YAML against the template schema. Example prompts: - "Generate a template YAML for a new Backstage component" - "Validate this template YAML for me" - "Create a component template for a microservice with GitHub and Jira" - **Plugin Data** - When plugins are enabled by your administrator, the Assistant can retrieve data from them. For example, it can retrieve issues from Jira, pull requests from GitHub, incidents from PagerDuty, or vulnerabilities from Snyk. Ask for assistance using natural language, and the Assistant will use the right integration. Example prompts: - "What are the open Jira issues for the payments project?" - "Show me recent PagerDuty incidents for the API service" - "List open pull requests for the frontend repo" - **MCP Servers** - Ask about MCP servers registered in your organization and the capabilities they expose. Example prompts: - "Which MCP servers are registered in our organization?" - "What tools does the Context7 MCP server provide?" - **Skills** - Ask about agent skills discovered from your connected repositories. Example prompts: - "What skills are available for Helm chart scaffolding?" - "Show me skills related to mkdocs navigation" - **Repository intelligence** - When [repository ingestion](../developer-portal/ingestion-and-summary.md) is enabled, ask for summaries or code context from repositories your teams own. Example prompts: - "Give me a summary of the checkout-service repository" - "How is authentication implemented in the payments-service repo?" ## Supported Plugins In general, the information about the plugins is based on the entity it is associated with. For example, the Jira plugin will return information about the Jira issues associated with the entity, and so on. The Assistant can retrieve data from the following plugin integrations when they are enabled in your Venue instance: | Plugin | Description | | --------------------- | ----------------------------------------------------------------------- | | **ArgoCD** | Deployment status and application health | | **Artifactory** | Artifact repository information | | **AWS Cost Insights** | AWS spending analysis and cost allocation | | **Bitbucket** | Repository information and pull requests | | **Confluence** | Search Confluence content across your organization | | **Datadog** | Monitoring and observability data | | **GitHub** | Repository info, commits, pull requests, issues, branches, and releases | | **GitLab** | Repository info, pipelines, merge requests, contributors, and releases | | **Jenkins** | Build and pipeline information | | **Jira** | Project details and open issues | | **Kubernetes** | Cluster and workload information | | **LaunchDarkly** | Feature flags, configurations, and evaluated flag values | | **Nexus** | Artifact repository information | | **PagerDuty** | Service info, incidents, on-call schedules, and standards | | **Snyk** | Security vulnerabilities, projects, and issues | | **SonarQube** | Code quality and analysis data | | **Terraform** | Workspace runs and assessment results | :::note Plugins must be enabled by your Venue administrator before the Assistant can access their data. If a plugin is not enabled or you see an error, contact your administrator. ::: ## Using Venue.sh Data in External AI Tools (MCP) You can use the same Venue.sh data (catalog, TechDocs, templates, and plugin integrations) from external AI tools that support the Model Context Protocol (MCP), such as Cursor and Claude Desktop. After you connect the Venue.sh MCP endpoint and sign in with your Venue account, the AI can query your organization's data in that tool, so you get rich, context-aware conversations without leaving your IDE or desktop app. For setup steps and what you can do, see [Venue MCP Endpoint](./mcp.md). ## MCP Servers and Skills Venue.sh also catalogs the AI tooling your organization uses: - **[MCP Servers](./mcp-servers.md)** - Register MCP servers by URL or manual entry, inspect their tools, resources, and prompts, and refresh capabilities as servers evolve. - **[Skills](./skills.md)** - Browse agent skills auto-discovered from `SKILL.md` files in connected Git repositories, following the [agentskills.io](https://agentskills.io/specification) specification. Both are available from the _AI_ section in the sidebar and are searchable through the Assistant. ## Setting Up the Assistant (Admin) Administrators configure the Assistant so users can chat and choose their models. All the setup is done in the Venue.sh dashboard. 1. Go to the Assistant settings in Venue.sh by clicking the **Settings** cog, then click the **Assistant** tab. 2. Create a new configuration via a template, or edit an existing one. | Template | Description | Best for | | ----------------- | --------------------------------------------------- | --------------------------------------- | | General OpenAI | Standard OpenAI setup with GPT models | Most organizations starting with AI | | General Anthropic | Standard Anthropic setup with Claude models | Teams preferring Claude | | DevOps Specialist | Optimized for infrastructure and deployment queries | DevOps-focused teams | | Multi-Provider | Multiple providers configured together | Organizations wanting model flexibility | 3. Configure one or more AI providers (OpenAI, Anthropic, Gemini, AWS Bedrock). 4. Add the required API keys, and select which models to allow your team to use. Users will be able to select and switch between these models when using the Assistant. :::tip Store API keys securely! Your Venue instance keeps them in a secure store and does not expose them in the UI once they're saved. ::: If you need help with the configuration, do not hesitate to [contact the Venue.sh team](https://venuesh.atlassian.net/servicedesk/customer/portal/2 'Support Portal'). ## Writing Effective Queries Here are a few best practices for writing useful queries and prompts: - **Be specific** - Include relevant details like team names, component types, and entity names. - **Speak clearly** - Converse with the Assistant using natural language, just as you would to a colleague. - **Use context** - Reference specific entities or projects when you know them. - **Iterate** - Refine your question based on the first answer, and use follow-up suggestions when necessary. :::tip Switch it up! If you use different AI tools for different types of work, or if you're curious and want to try another model, you can switch AI models easily. Conversations are kept in history for recall and review, or you can delete them when no longer needed. ::: ## Limitations & Considerations While the Assistant is an impressive helper, it's not perfect. Here are a few things to keep in mind as you use the feature. - **Data freshness** - The Assistant works with data from your Venue instance, which is refreshed periodically. For real-time data, always verify against the source systems. - **Model-specific capabilities** - Different AI models may have varying capabilities and limitations. If you're not getting the results you expect, try switching models. ## Troubleshooting | Situation | What to do | | ------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | No models appear / "Configuration not available" | Your administrator needs to create an Assistant configuration and add at least one provider and model. Ask them to go to **Settings > Assistant** to make the updates. | | A plugin returns an error or no data | The integration may not be enabled or may need configuration. Contact your Venue administrator. | | Results seem outdated | The Assistant uses data from your Venue instance, which is refreshed periodically. For real-time data, check the source system. | | You're not getting satisfactory results | Use the dropdown to switch and try a different AI model. Some models are better at certain tasks than others. | ## Support & Feedback If you encounter issues or have suggestions for improving the Assistant: - Contact your Venue administrator, or - Submit a support ticket through the [Venue.sh Support Portal](https://venuesh.atlassian.net/servicedesk/customer/portal/2 'Support Portal'). --- ## MCP Servers MCP Servers in Venue.sh let your organization register, discover, and inspect Model Context Protocol (MCP) servers in one place. Platform teams get a shared registry of available AI tools, and developers can browse what each server exposes before wiring it into an IDE or agent workflow. The MCP Server catalog is separate from [Venue's built-in MCP endpoint](./mcp.md), which lets external AI tools query your Venue.sh data. The catalog is for documenting _any_ MCP server your organization uses - internal services, vendor integrations, or local development servers. ## Key Capabilities - **Registration** - Register MCP servers by URL (auto-extract capabilities) or by manual entry. - **Discovery** - Browse and search registered servers across your organization. - **Inspection** - View the tools, resources, and prompts exposed by each server. - **Refresh** - Re-extract capabilities for URL-registered servers when they change. - **Assistant integration** - Ask the Assistant about registered servers using natural language. Registered MCP servers are also synced to the software catalog as MCPServer entities, so you can relate them to Components and other catalog entities. ## Browsing MCP Servers 1. Open _MCP Servers_ from the sidebar (under _AI_). 2. Use the search box to filter by name or description. 3. Click a server to open its detail page. Each list row shows the server name, description, transport type, status, and counts for tools, resources, and prompts. ## Registering an MCP Server Admins and Editors can register, edit, and delete MCP servers. Contributors, Viewers, and Demo users can browse servers but cannot add or edit them. ### URL-based registration (recommended) URL-based registration connects to the MCP server, performs the protocol handshake, and automatically extracts its tools, resources, and prompts. 1. Go to _MCP Servers_ and click **Add MCP Server**. 2. Enter a **name** and optional **description**. 3. Enter the server **URL** (_e.g.,_ `https://mcp.example.com/mcp`). 4. If the server requires authentication, choose a credential type and provide the values: - **Bearer token** - **API key** (with optional custom header name) - **Basic auth** (username and password) - **Custom header** (name and value) 5. Submit the form. Venue.sh connects to the server and populates its capabilities. Credentials are stored securely. They are never shown in the UI or returned by API responses after registration. ### Manual registration Use manual registration when the server is not reachable from Venue.sh, or when you want to document capabilities without a live connection. 1. Go to _MCP Servers_ and click **Add MCP Server**. 2. Switch to manual registration mode. 3. Enter server metadata (name, description, transport type). 4. Add tools, resources, and prompts via the form. Manual servers do not support on-demand capability refresh. Update them by editing the record. ## Viewing MCP Server Details The detail page shows: - **Metadata** - Name, description, URL, transport, status, and whether credentials are configured. - **Tools** - Name, description, and input schema where available. - **Resources** - URI patterns, names, MIME types, and descriptions. - **Prompts** - Name, description, and argument lists. For URL-registered servers, click **Refresh Capabilities** to re-connect and update the stored tools, resources, and prompts. If the server is unreachable during refresh, the previous capabilities are retained and an error is shown. ## Useful Things to Ask About The Assistant can answer questions about your registered MCP servers. For example: - "Which MCP servers are registered in our organization?" - "What tools does the Atlassian MCP server expose?" - "List all MCP servers with more than 10 tools." The Assistant uses the same catalog data shown on the MCP Servers pages. ## Permissions MCP Server access follows the same pattern as repository content: | Role | Permissions | | ------------------------- | -------------------------------- | | Admin, Editor | Create, Read, Update, and Delete | | Contributor, Viewer, Demo | Read only | Registration, updates, and deletions are recorded in the [Activity Log](../activity-log.md). ## Troubleshooting | Situation | What to do | | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- | | Registration fails with a connection error | Verify the URL is correct and the server is reachable from Venue.sh. Check that credentials are valid if required. | | Server registered with empty capabilities | The server may have connected but reported no tools, resources, or prompts. Confirm the server is fully configured on the provider side. | | Refresh fails | The server may be down or credentials may have expired. The previously stored capabilities are kept until a successful refresh. | | Duplicate server error | A server with the same URL is already registered in your organization. Edit the existing record instead. | | Cannot see the Add button | Your role may not include MCP Server create permission. Only Admins and Editors can register servers. Contact your Venue administrator. | ## See Also - [Venue MCP Endpoint](./mcp.md) - Connect external AI tools (Cursor, Claude Desktop) to query Venue.sh data. - [Skills](./skills.md) - Browse agent skills auto-discovered from connected repositories. - [Assistant](./assistant.md) - Using the Assistant in the Venue.sh portal. --- ## Venue MCP Endpoint Venue.sh exposes a built-in _MCP (Model Context Protocol) endpoint_ so you can use your organization's catalog, documentation, templates, and plugin data from AI tools that support MCP. Using the endpoint is as simple as adding it to your AI tool's settings and signing in with your Venue.sh account. :::tip[Two MCP features] This page covers Venue.sh's built-in MCP endpoint - the URL your IDE or desktop app connects to for OAuth access to Venue data. To register and browse MCP servers your organization uses (_e.g.,_ Atlassian, Context7, or internal services), see [MCP Servers](./mcp-servers.md). ::: The endpoint provides the same capabilities that are available in the Venue.sh Assistant: - **Software catalog** - Search and fetch entities (APIs, Components, Groups, Locations, Rules, Templates, Users) - **Technical documentation** - Search and read TechDocs - **Templates** - Get template schemas and validate YAML for scaffolding - **Plugin integrations** - Data from enabled plugins (Jira, GitHub, GitLab, PagerDuty, Snyk, Confluence, and the other [supported plugins](./assistant.md#supported-plugins)) ## How It Works - First, you add the Venue.sh MCP endpoint in your AI tool (Cursor or Claude Desktop), using your Venue.sh dashboard URL. - Once the tool connects, you sign in with your Venue.sh account (OAuth in the browser). - After that, the tool can use your organization's data to answer questions. You stay in your IDE or desktop app with full context. Your Venue.sh administrator does not need to enable anything extra for MCP. If you can use the Assistant in the Venue.sh portal, you can use the same data via MCP once the server is connected and you're signed in. ## Connecting to the Venue MCP Endpoint The exact steps depend on your AI tool. Look for options like "Add MCP server," "Remote server," or "OAuth" and use your Venue.sh dashboard base URL plus `/mcp`. If your tool asks for OAuth metadata, it can discover it from your Venue.sh instance automatically. :::info[Prerequisites] - A Venue.sh account and access to your organization's Venue.sh instance - Your Venue.sh dashboard URL (`https://dashboard.venue.sh`) - An AI application that supports MCP with OAuth (_e.g.,_ Cursor, Claude Desktop) ::: ### Cursor 1. Open **Cursor Settings** > **MCP** (or **Features** > **MCP**). 2. Add the following: ```json { "venuesh": { "url": "https://dashboard.venue.sh/mcp" } } ``` 3. When Cursor connects, complete the sign-in flow in the browser with your Venue.sh account. ### Claude Code 1. Run the following command to add the Venue.sh MCP server to Claude Code: ```bash claude mcp add --transport http venuesh https://dashboard.venue.sh/mcp ``` 2. Sign in with your Venue.sh account when prompted. ### Claude Desktop 1. Open **Claude** > **Settings** > **Developer** > **Edit Config**. 2. Add an MCP server entry that points to your Venue dashboard URL, (`https://dashboard.venue.sh/mcp`). 3. Restart Claude Desktop. 4. Sign in with your Venue.sh account when prompted. :::tip If your tool supports "OAuth-protected resource" or "resource metadata" URLs, the Venue MCP endpoint publishes the required metadata so the tool can complete the OAuth flow. ::: ## Troubleshooting | Situation | What to do | | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- | | Sign-in fails or "Authentication required" | Ensure you use the same Venue dashboard URL your organization uses and that you have an active Venue account. Try signing in again in the browser. | | No data or "Organization not found" | Your user must be linked to at least one organization in Venue.sh. Contact your Venue.sh administrator if you don't have access. | | Tool not connecting | Check that the URL is correct, including `https://` and `/mcp`. | | Plugin data missing | Same as in the portal: Plugins must be enabled by your administrator. The AI can only use data from integrations that are enabled for your instance. | ## See Also - [Assistant](./assistant.md) - Using the Assistant in the Venue.sh portal. - [MCP Servers](./mcp-servers.md) - Register and browse MCP servers in your organization. - [Skills](./skills.md) - Browse agent skills auto-discovered from connected repositories. - [Supported Plugins](./assistant.md#supported-plugins) - A list of integrations available to the Assistant and MCP. --- ## Skills Skills in Venue.sh are reusable AI workflow instructions - step-by-step guidance that coding agents load when a task matches the skill's trigger conditions. Venue.sh automatically discovers and catalogs skills from your connected Git repositories. Skills follow the [agentskills.io specification](https://agentskills.io/specification). You do not register skills manually. Venue.sh finds them during repository content ingestion and keeps the catalog in sync as repositories change. ## Key Capabilities - **Discovery** - Browse skills discovered across your organization's connected repositories. - **Search** - Filter by name or description keywords. - **Inspection** - View skill metadata, including triggers, author, version, license, and companion content inventory. - **Reading** - View the rendered markdown from each skill's `SKILL.md` file. - **Assistant integration** - Ask the Assistant about available skills using natural language. Discovered skills are also synced to the software catalog as Skill entities, so you can relate them to Components and other catalog entities. ## Browsing Skills 1. Open _Skills_ from the sidebar (under _AI_). 2. Use the search box to filter by name or description. 3. Click a skill to open its detail page. The list shows each skill's name, description, source repository, and when it was last updated. :::info[How skills appear] Skills are discovered automatically when repository content ingestion finds `SKILL.md` files in connected repositories. New skills appear after the next ingestion run. Removed skills are dropped from the catalog when their `SKILL.md` file is deleted. For prerequisites and configuration, see [Ingestion & Summary](../developer-portal/ingestion-and-summary.md). ::: ## Viewing Skill Details Each skill detail page shows: - **Metadata** - Name, description, trigger summary, author, version, license, compatibility, and allowed tools (when present in frontmatter). - **Companion content inventory** - Which optional directories exist alongside the skill (`scripts/`, `references/`, `agents/`, `assets/`, `rules/`) and how many files each contains. - **Source** - The repository and directory path where the skill was discovered. - **Skill body** - The rendered markdown content from `SKILL.md`. The trigger summary is extracted from phrases like "Use when..." in the skill description or body, helping you quickly see when an agent should load the skill. ## Authoring Skills in Your Repository To make a skill discoverable in Venue.sh, add a skill directory to a connected repository with a `SKILL.md` file at its root. The filename is matched case-insensitively (`SKILL.md` or `skill.md`). ### Directory structure A skill is a directory, not a single file. The minimum requirement is `SKILL.md`. Optional companion directories provide supporting material: ``` my-skill/ ├── SKILL.md # Required - skill definition and instructions ├── scripts/ # Optional - executable scripts the agent can run ├── references/ # Optional - reference documents ├── agents/ # Optional - agent definitions ├── assets/ # Optional - images, templates, or other assets └── rules/ # Optional - rule files ``` Venue.sh catalogs the companion directory inventory and file counts. It does not ingest the full content of companion files into the Skills catalog. ### SKILL.md format `SKILL.md` uses YAML frontmatter followed by markdown body content: ```markdown --- name: my-skill description: Short summary of what this skill does. Use when the user asks to sync mkdocs navigation. license: Apache-2.0 compatibility: Cursor, Claude Code metadata: author: Platform Team version: '1.0' allowed-tools: bash, read, write --- # My Skill Detailed instructions for the agent go here. ## Workflow 1. Step one 2. Step two ``` #### Frontmatter fields | Field | Required | Description | | --------------- | ----------- | --------------------------------------------------------------------------------------- | | `name` | Yes | Lowercase identifier (letters, numbers, hyphens; max 64 characters) | | `description` | Recommended | Brief summary (max 1024 characters). Include "Use when..." to define trigger conditions | | `license` | No | SPDX license identifier or free text | | `compatibility` | No | Which agents or tools the skill supports (max 500 characters) | | `metadata` | No | Key-value map for additional fields such as `author` and `version` | | `allowed-tools` | No | Tools the skill expects the agent to use (experimental) | If frontmatter is missing or incomplete, Venue.sh derives the skill name from the directory name and extracts a description from the first paragraph of the markdown body. ### Common locations Skills can live anywhere in a connected repository. Common conventions include: - `.cursor/skills//SKILL.md` - Cursor plugin and workspace skills - `skills//SKILL.md` - Repository-level skills Skills with the same name in different repositories are treated as separate catalog entries, disambiguated by their source repository. ## Useful Things to Ask About The Assistant can answer questions about skills discovered from your connected repositories. For example: - "What skills are available for Helm chart scaffolding?" - "Show me skills related to mkdocs navigation" ## Permissions Skill catalog access follows the same pattern as repository content: | Role | Permissions | | ---------------------------------------- | ---------------------- | | Admin, Editor, Contributor, Viewer, Demo | Read (list and detail) | Skills are created, updated, and removed automatically by the ingestion pipeline. There is no manual registration or deletion in the dashboard. ## Troubleshooting | Situation | What to do | | ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Skill not appearing after commit | Wait for the next repository content ingestion run. Confirm the repository is connected, ingestion is enabled, and the file is named `SKILL.md` (case-insensitive). See [Ingestion & Summary](../developer-portal/ingestion-and-summary.md). | | Skill disappeared from the catalog | The `SKILL.md` file or its parent directory may have been removed from the repository. | | Invalid skill name error | The `name` field must use only lowercase letters, numbers, and hyphens (max 64 characters). | | Missing trigger summary | Add a "Use when..." phrase to the `description` frontmatter field or the markdown body. | | Cannot access the Skills page | All roles should have Skills read access. If the page is missing, contact your Venue administrator. | ## See Also - [MCP Servers](./mcp-servers.md) - Register and inspect MCP servers in your organization. - [Venue MCP Endpoint](./mcp.md) - Connect external AI tools to query Venue.sh data. - [Assistant](./assistant.md) - Using the Assistant in the Venue.sh portal. - [Importing Repositories](../developer-portal/importing-repos.md) - Connect Git repositories for catalog ingestion. - [Ingestion & Summary](../developer-portal/ingestion-and-summary.md) - Enable repository indexing and AI summaries. --- ## Connect with Bitbucket Cloud The integration with Bitbucket Cloud allows you to sync repositories to Venue.sh as entities. :::info[Prerequisites] - An organization in Venue.sh - A role of _Editor_ or above - A Bitbucket account with an appropriate permission level ::: ### Creating an app password :::note [Bitbucket's documentation](https://support.atlassian.com/bitbucket-cloud/docs/app-passwords/) on creating app passwords describes the process in detail. While we endeavour to keep this document current, Bitbucket's process may have changed. ::: 1. Go to [https://bitbucket.org/](https://bitbucket.org/) and sign in. 2. Click **Setting** > **Personal Bitbucket settings** > **App passwords**. 3. Click **Create app password**. :::tip [Here's a shortcut](https://bitbucket.org/account/settings/app-passwords/new) if you want to save some clicks. ::: 4. Give the app password a name. 5. Choose the following scopes/permissions for the token: - **Account** - Email - Read - **Workspace membership** - Read - **Projects** - Read - **Repositories** - Read - Write - **Pull requests** - Read - **Pipelines** - Read 6. Click **Create**. 7. Take note of the app password as it cannot be retrieved once you leave the page. ### Creating an OAuth app To fully integrate Bitbucket Cloud with Venue.sh, you must set up an OAuth app. 1. Go to [https://bitbucket.org/``/workspace/settings/api](#) 2. Click **Add Consumer**. 3. Insert the following properties: - **Application name:** `Venue.sh` - **Callback URL:** `https://.venue.sh/api/auth/bitbucket` :::tip Your organizations **Callback URL** can be found in app when adding a Bitbucket Cloud connection on the right sidebar. ::: 4. Choose the following scopes/permissions for the application: - **Account** - read - **Workspace membership** - read 5. Click **Save**. 6. Take note of the **Client ID** and **Client Secret** values. --- ## Connect with Bitbucket DC The integration with Bitbucket DC allows you to sync repositories to Venue.sh as entities. :::info[Prerequisites] - An organization in Venue.sh - A role of *Owner* or above - A Bitbucket DC account with an appropriate permission level ::: ### Creating a Personal Access Token :::note [Bitbucket's documentation](https://confluence.atlassian.com/bitbucketserver/personal-access-tokens-939515499.html) on creating personal access tokens describes the process in detail. While we endeavour to keep this document current, Bitbucket's process may have changed. ::: 1. Sign in to your hosted instance of Bitbucket DC. 2. Click your profile pic, then select **Manage account** > **HTTP access tokens** > **Create token**. 3. Set a token name. 4. Choose the following scopes/permissions for the token: - **Project permissions** - Project write - **Repository permissions** - Repository write 5. Click **Create**. 6. Take note of the personal access token as it cannot be retrieved once you leave the page. ### Creating an OAuth app To fully integrate Bitbucket with Venue.sh, you must set up an OAuth app. 1. Sign in to your hosted instance of Bitbucket DC. 2. Go to **Administration** > **Applications** > **Application links**. 3. Select **Create link**. 4. Select **External application**, and then choose **Incoming** as the direction. 5. Insert the following properties: - **Application name:** `Venue.sh` - **Callback URL:** `https://.venue.sh/api/auth/bitbucket` :::tip Your organizations **Callback URL** can be found in app when adding a Bitbucket DC connection on the right sidebar. ::: 6. Choose the following scopes/permissions for the application: - **Projects** - Admin - **Repositories** - Read - Write 7. Click **Save**. 8. Take note of the **Client ID** and **Client Secret** values. --- ## Git Connect your Venue.sh instance with your desired version control system to sync your repository metadata. Navigate to https://dashboard.venue.sh/connections/git/new to get started. Detailed instructions to connect each system can be found within this section of the documentation. --- ## Connect with GitHub Our integration with GitHub allows you to sync repositories to Venue.sh as entities. :::info[Prerequisites] - An existing organization in Venue.sh - A role of _Owner_ or above - A Github account or organization with an _Owner_ permission level ::: ## Creating a Personal Access Token As a best practice, we recommended setting up a dedicated service account for this token. :::note [GitHub's documentation](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token) describes the token-creation process in detail. While we endeavour to keep this document current, GitHub's process may have changed. ::: 1. Go to [https://github.com](https://github.com/) and sign in. 2. Click your profile pic, then select **Settings** > **Developer Settings** > **Personal Access Tokens** > **Tokens (classic)**. :::tip Here's [a shortcut](https://github.com/settings/tokens) if you want to save some clicks. ::: 3. Click the **Generate new token** dropdown, then select [**Generate new token (classic)**](https://github.com/settings/tokens/new). 4. Give the token a name and define its expiration period. :::tip Remember, when the token expires, you will need to replace it to ensure no lapse in functionality. ::: 5. Choose the following scopes/permissions for the token: - **repo** - repo:status - repo_deployment - public_repo - repo:invite - security_events - **workflow** - **admin:org** - read:org - **user** (required to receive webhook changes from GitHub): - read:user - user:email 6. Click **Generate token**. 7. Take note of the personal access token as it cannot be retrieved once you leave the page. ## Creating an OAuth app To fully integrate GitHub with Venue.sh, you must set up an OAuth app. 1. Go to [https://github.com/settings/organizations](https://github.com/settings/organizations) and sign in. 2. Ensure your desired organization is selected, then click **Settings**. 3. Scroll to the bottom of the left menu, then click **Developer Settings** > **OAuth Apps**. 4. Click on **New Oauth App**, and insert the following properties: - **Application name:** Venue.sh - **Homepage URL:** `https://.venue.sh` - **Callback URL:** `https://.venue.sh/api/auth/github/handler/frame` :::tip Your organization's **Homepage URL** and **Callback URL** can be found on the right-hand sidebar in the Venue.sh app when adding a Github connection. ::: 5. Click **Register Application**. 6. Click **Generate a Client Secret**. 7. Take note of the `Client ID` and `Client secret` values. --- ## Connect with GitLab Our integration with Gitlab allows you to sync repositories to Venue.sh as entities. :::info[Prerequisites] - An organization in Venue.sh - A role of *Owner* or above - A GitLab account with an appropriate permission level ::: ### Creating a Personal Access Token :::tip As a best practice, we recommended setting up a dedicated service account for this token. ::: :::note [GitLab's documentation](https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html) on creating personal access tokens describes the process in detail. While we endeavour to keep this document current, GitLabs's process may have changed. ::: 1. Go to [https://gitlab.com](https://gitlab.com) or your hosted instance of GitLab and sign in. 2. Click your profile pic, then select **preferences** > **Access Tokens** > **Add new token**. 3. Give the token a name and define its expiration period. > **TIP:** Remember, when the token expires, you will need to replace it to ensure no lapse in functionality. 4. Choose the following scopes/permissions for the token: - **api** - **read_repository** - **write_repository** 5. Click **Create personal access token**. 6. Copy the token as it cannot be retrieved once you leave the page. ### Creating an OAuth app To fully integrate Gitlab with Venue.sh, you must set up an OAuth app. 1. Go to [https://gitlab.com](https://gitlab.com/) or your hosted instance of GitLab and sign in. 2. Click your profile pic, then select **preferences** > **Applications** > **Add new application**. 3. Insert the following properties: - **Name:** `Venue.sh` - **Redirect URI:** `https://.venue.sh/api/auth/gitlab/handler/frame` :::tip Your organizations **Redirect URI** can be found in app when adding a Gitlab connection on the right sidebar. ::: 4. Choose the following scopes/permissions for the application: - **Confidential** - **read_user** - **read_repository** - **write_repository** - **openid** - **profile** - **email** 5. Click **Save application**. 6. Take note of the Application ID and Secret. 7. Click **Continue**. --- ## Developer Portal The Developer Portal provides users with a central space to view and manage a company’s repositories. This platform helps improve collaboration among developers, increase productivity, and streamline the overall development process. ## Key Features - **Syncing** - Link your instance to GitHub, GitLab, and Bitbucket to start syncing repositories to Venue.sh as entities. - **Integrations** - Enable integrations with tools like SonarQube and Jira to generate insights about your entities. - **Service Ownership** - Establish clear ownership of services to ensure accountability and streamlined operations. - **API Specs** - Provides accurate and easy-to-find API specifications for developers, making it easier to integrate with other systems. - **Templates** - Utilize our tested and validated templates or create your own to quickly launch your next project or tailor a custom template to fit your team's unique needs. - **Ingestion & Summary** - Index imported repositories for AI summaries, repository-aware Assistant answers, and automatic Skills discovery. See [Ingestion & Summary](./ingestion-and-summary.md). - **Assistant** - Use the AI Assistant to ask questions about your catalog, documentation, and integrations in natural language with your Venue instance as context, you get rich, context-ready conversations without switching tools. --- ## Importing Repos Managing owners now have a better way to import repositories into Venue.sh—either one repo at a time or many at once—in a simple, user-friendly process. Gone are the days of creating `yaml` files from scratch and adding details to Backstage via template. Now you can import and manage as many repos as you like in a matter of minutes, all without writing a single line of code. Importing repos is part of the onboarding process for Venue owners. The four onboarding steps appear on the _Home_ screen until each step is completed. To reiterate, the four onboarding steps for owners are as follows: 1. [Create a connection](/docs/connections/git/) 2. [Create a team](/docs/get-started/users-and-teams/#team-settings) 3. [Enable plugins](/docs/plugins/) 4. Import repositories :::note The _Get started with Venue.sh_ onboarding will disappear from the _Home_ screen once all four onboarding steps are complete. ::: ## Importing Repos into Venue.sh Begin the import process from your Venue _Home_ screen. :::info[prerequisites] Ensure onboarding Steps 1--3 (outlined above) are complete before your import repos. ::: 1. Click one of the following options, each of which leads to the same import process: - **Run an import** from the _Quick Start_ tile - **Step 4: Import repositories** from the onboarding steps - **Imports** from the left-side navigation The _New Import_ wizard appears. 2. Select the Git connection from which you want to pull a list of repos, then click **Next step**. A list of available repos is generated on the sceen. 3. Select the repos you want to import into the venue, then click **Next step**. The configuration screen appears. 4. Select your metadata preferences for each repo from the drop-down options, and type your desired values into the free-text fields, _e.g._, **Namespace** and **Tags**. :::note - Adding metadata details to new entities helps track entities within the Venue catalog. - You can only add a single value for **Namespace** and **Tag**; however, you can edit the component post-import (Step 8) and add additional values if you'd like. ::: 5. OPTIONAL: If active, click **Configure optional fields** to select and add fields from your enabled plugins to the configuration table. If no plugins are enabled, this button will be inactive. 6. Click **Next step**. The _Finalize import_ summary appears. 7. Review the values and, once approved, click **Import**. The import runs, and a success message appears. 8. Click **Go to Catalog** to view and/or edit the new components. :::tip In the catalog, filter results using the options on the left side of the page, or use the keyword search. Click **Edit** to make updates to a component or other entities within the catalog. You can update the title, description, add additional **Namespace** and **Tag** values, and more. ::: ## See Also - [Ingestion & Summary](./ingestion-and-summary.md) - Index imported repositories for AI summaries and repository-aware Assistant answers. --- ## Ingestion & Summary Repository content ingestion in Venue.sh indexes source code from your connected Git repositories so your organization can search repository content, generate AI summaries, and discover [Skills](../ai/skills.md) from `SKILL.md` files. Ingestion runs in the background after repositories are imported into the catalog. Administrators configure ingestion and summary generation under **Settings > Ingestion & Summary**. ## Key Capabilities - **Repository indexing** - Pull repository content, chunk source files, and build searchable embeddings for your organization. - **AI summaries** - Generate structured summaries (purpose, technologies, architecture, and key components) for catalog entities linked to repositories. - **Assistant integration** - Let the [Assistant](../ai/assistant.md) answer repository summary and code questions using ingested content. - **Skills discovery** - Automatically catalog agent skills from `SKILL.md` files during ingestion (see [Skills](../ai/skills.md)). ## How Ingestion Works When repository ingestion is enabled for your organization, Venue.sh starts an ingestion job automatically in these situations: - You [import repositories](./importing-repos.md) into the catalog. - A catalog entity with an associated repository is created or updated. Each job indexes the repository's source content. When the job completes, search and summary features use the latest indexed snapshot. If ingestion is disabled, new jobs are not started. :::info[Prerequisites] - A Git connection and imported repositories with valid source locations in the catalog. - Repository ingestion enabled under **Settings > Ingestion & Summary**. - For AI summaries, **Repository Summary** must also be enabled on the same settings page. ::: ## Configuring Ingestion & Summary (Admin) Administrators manage ingestion from **Settings > Ingestion & Summary** (`/settings/ingestion-summary`). You need permission to configure Assistant settings to view or update this page. 1. Open **Settings** and select **Ingestion & Summary**. 2. Configure **Repository Ingestion** and **Repository Summary** as described below. 3. Click **Save changes**. Changes apply to future ingestion jobs and summary generation requests. ### Repository Ingestion Use the **Repository Ingestion** switch to enable or disable indexing for your organization. When you disable ingestion, **Repository Summary** is turned off as well. Choose an embedding mode: | Mode | Description | | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Managed Ingestion** | Venue.sh handles repository ingestion and keeps the underlying embedding configuration out of the way. Recommended for most organizations. | | **Bring Your Own Model** | Connect a self-hosted Ollama embedding endpoint. Provide the **Ollama Base URL**, **Model Name**, and an **API Key** if your endpoint requires authentication. | :::info[Other embedding options] If you want to use a different embedding providers such as Voyage AI or Cohere, please reach out to the Venue.sh team. ::: ### Repository Summary When **Repository Ingestion** is enabled, you can turn on **Repository Summary** to generate AI summaries for indexed repositories. By default, Venue.sh uses **Managed Summary** and creates summaries automatically after ingestion completes. Under **Advanced**, you can enable **Use Assistant Configuration** and select an existing Assistant configuration and model for summary generation. You must have at least one Assistant configuration with allowed models before using this option (see [Setting Up the Assistant (Admin)](../ai/assistant.md#setting-up-the-assistant-admin)). ## Viewing Repository Summaries When a summary exists for a catalog entity linked to a repository, a **Summary** tab appears on the entity detail page (after **Overview**). The summary includes: - **Purpose** - What the repository or service does. - **Technologies** - Languages, frameworks, or tools detected in the codebase. - **Architecture** - High-level structural overview. - **Key components** - Notable modules or areas of the codebase. - **Conventions** - Coding or repository conventions when available. If no summary tab appears, the repository may not be ingested yet, summary generation may be disabled, or a summary has not been generated for that repository. ## Using Ingestion with the Assistant When ingestion is enabled and a repository has been indexed, the Assistant can help with repository-aware questions. For example: - "Give me a summary of the checkout-service repository." - "How is authentication implemented in the payments-service repo?" - "Where is the database connection configured in frontend-app?" The Assistant resolves repositories by name, URL, or catalog context. You do not need to provide internal repository IDs. Repository search respects team ownership. You can only search repositories your teams own in the catalog. If you see no results or an access error, confirm your team membership and the entity's owner metadata. ## Skills Discovery During ingestion, Venue.sh scans repository files for `SKILL.md` definitions and updates the [Skills](../ai/skills.md) catalog. New or updated skills appear after the next successful ingestion run for that repository. Removed `SKILL.md` files are dropped from the catalog on a subsequent run. ## Permissions | Action | Who can do it | | ---------------------------------------------------- | -------------------------------------------------------------------- | | View **Ingestion & Summary** settings | Users with Assistant settings read access (typically administrators) | | Update ingestion and summary settings | Users with Assistant settings create/update access (administrators) | | View repository summaries in the catalog | Users with catalog read access to the entity | | Search ingested repository content via the Assistant | Users who belong to a team that owns the repository | Ingestion jobs triggered by import or entity updates are recorded in the [Activity Log](../activity-log.md). ## Troubleshooting | Situation | What to do | | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | No **Ingestion & Summary** menu item | Your role may not include Assistant settings access. Contact your Venue administrator. | | Ingestion never runs | Confirm **Repository Ingestion** is enabled and repositories are imported with a valid source location annotation. | | No **Summary** tab on an entity | Enable **Repository Summary**, wait for ingestion to complete, and confirm the entity is linked to a repository. | | Assistant cannot answer code questions | The repository may not be ingested yet, ingestion may be disabled, or you may not have access to that repository's owning team. | | Skills not appearing | Wait for the next ingestion run after committing `SKILL.md` files. Confirm the repository is connected and ingestion is enabled. See [Skills](../ai/skills.md#troubleshooting). | | Ollama mode fails | Verify the base URL, model name, and API key. Ensure Venue.sh can reach your Ollama endpoint from its environment. | ## See Also - [Importing Repositories](./importing-repos.md) - Connect and import repositories into the catalog. - [Assistant](../ai/assistant.md) - Ask questions about catalog, documentation, and ingested repositories. - [Skills](../ai/skills.md) - Browse agent skills discovered during ingestion. - [Activity Log](../activity-log.md) - Audit trail for ingestion events. --- ## Template Examples This section provides practical examples of templates you can use and adapt for your organization. ## Creating an AWS S3 Bucket Template Follow this example to create a simple AWS S3 bucket. Venue.sh will take variables defined in your template steps and replace your template files with the actual values when used. ```shell title="File Structure" . ├── providers.tf ├── main.tf ├── variables.tf ├── docs │ └── index.md ``` ```terraform title="providers.tf" terraform { required_providers { aws = { source = "hashicorp/aws" version = "~> 6.0" } } } provider "aws" { region = var.region default_tags { tags = { "BusinessUnit" = "purplehotels-devops" "Department" = "product-${{ values.environment }}" "Team" = "purplehotels-devops" "Stage" = "${{ values.environment }}" "Support:Email" = "support@purplehotels.com" "Support:Slack" = "purplehotels:support" "Support:Url" = "https://purplehotels.atlassian.net/jira/servicedesk/projects/PH/queues/custom/4" } } } ``` ```terraform title="main.tf" resource "aws_s3_bucket" "${{ values.bucket_name }}_s3_bucket" { bucket = "s3-${{ values.bucket_name }}" } ``` ```terraform title="variables.tf" variable "region" { type = string default = "${{ values.region }}" } ``` ```markdown title="docs/index.md" # ${{ values.bucket_name }} (Terraform AWS S3) ## Values - name: ${{ values.bucket_name }} - region: ${{ values.region }} - environment: ${{ values.environment }} ``` When creating a template, each `${{ values.variable }}` that you define in your files must also be defined in the variables step. In the following example, we split the variables into two steps. While you can define your variables however you desire, we recommend splitting them into multiple steps. ## Creating an AWS EC2 Instance Template Follow this example to create a simple AWS EC2 instance. Venue.sh will take variables defined in your template steps and replace your template files with the actual values when used. ```shell title="File Structure" . ├── providers.tf ├── main.tf ├── variables.tf ├── docs │ └── index.md ``` ```terraform title="providers.tf" terraform { required_providers { aws = { source = "hashicorp/aws" version = "~> 6.0" } } } provider "aws" { region = var.region default_tags { tags = { "BusinessUnit" = "purplehotels-devops" "Department" = "product-${{ values.environment }}" "Team" = "purplehotels-devops" "Stage" = "${{ values.environment }}" "Support:Email" = "support@purplehotels.com" "Support:Slack" = "purplehotels:support" "Support:Url" = "https://purplehotels.atlassian.net/jira/servicedesk/projects/PH/queues/custom/4" } } } ``` ```terraform title="main.tf" resource "aws_instance" "${{ values.instance_name }}" { ami = "resolve:ssm:/aws/service/ami-amazon-linux-latest/al2023-ami-kernel-default-x86_64" instance_type = "${{ values.instance_type }}" subnet_id = "${{ values.subnet_id }}" key_name = "${{ values.key_name }}" vpc_security_group_ids = [ "${{ values.security_group_id }}" ] root_block_device { volume_size = ${{ values.root_volume_size }} volume_type = "${{ values.root_volume_type }}" encrypted = true delete_on_termination = true } metadata_options { http_tokens = "required" http_endpoint = "enabled" } } ``` ```terraform title="variables.tf" variable "region" { type = string default = "${{ values.region }}" } variable "instance_type" { type = string description = "EC2 instance type" default = "${{ values.instance_type }}" } variable "root_volume_size" { type = number description = "Root volume size in GB" default = ${{ values.root_volume_size }} } variable "root_volume_type" { type = string description = "Root volume type (gp3, gp2, io1, etc.)" default = "${{ values.root_volume_type }}" } ``` ```markdown title="docs/index.md" # ${{ values.instance_name }} (Terraform AWS EC2) ## Values - name: ${{ values.instance_name }} - region: ${{ values.region }} - environment: ${{ values.environment }} - instance_type: ${{ values.instance_type }} - subnet_id: ${{ values.subnet_id }} - security_group_id: ${{ values.security_group_id }} - key_name: ${{ values.key_name }} - root_volume_size: ${{ values.root_volume_size }} - root_volume_type: ${{ values.root_volume_type }} ``` When creating a template, each `${{ values.variable }}` that you define in your files must also be defined in the variables step. In the following example, we split the variables into two steps. While you can define your variables however you desire, we recommend splitting them into multiple steps. --- ## Templates Using templates guides users through the process of creating new entities, such as microservices, libraries, and more. Templates help enforce best practices and ensure consistency across projects. Templates can include various steps to automate the setup of new projects, such as: - Fetching base templates or boilerplate code from repositories - Generating files and directories with customized content - Initializing version control repositories - Setting up CI/CD pipelines - Registering the new component in the component catalog ## Using a Template To use a template, click **Create** via the dashboard sidebar, then select a desired template from the list. Fill in the required parameters, such as the service name, and initiate the creation process. The developer platform then uses the template to scaffold a new project based on the provided parameters. ## Consistency and Best Practices By using templates, organizations ensure that new projects adhere to established standards and best practices. Templates encapsulate knowledge about the organization's preferred tools, configurations, and conventions, reducing the learning curve for new developers and increasing overall productivity. ## References If you'd like to learn more about templates, check out the [Backstage Software Templates](https://backstage.io/docs/features/software-templates/) page. --- ## Dashboards Development Insights dashboards use interactive charts and tables to visualize your engineering metrics, commits, pull requests, and contributor activity. Dashboards are created automatically when the feature is enabled and populate with data as your repositories are imported. ## Dashboard List Opening **Development Insights** from the sidebar takes you to the dashboard list. This table shows all dashboards available to your organization with two columns: - **Dashboard Name** — Click the name to open the dashboard. - **Provider** — The data source the dashboard visualizes (e.g., GitHub, GitLab, Jira). Jira dashboards have an overflow menu (⋯) next to the provider name with a **Manage Connections** shortcut that takes you to the [Jira Connections](./jira-connections.md) page. :::note If no dashboards appear, the feature may not be enabled or no repositories have been imported yet. Ask your administrator to verify that [Development Insights is enabled](./development-insights.md#enabling-development-insights). ::: ## Dashboard Controls First, click a dashboard name in the list to open it. With an open dashboard, you have several controls to focus on the data that matters to you. ### Date Range Use the **Date Range** selector in the top-right corner to adjust the time window. Available ranges include: - Last 15 minutes, 1 hour, 3 hours, 6 hours, 12 hours, 24 hours - Last 2 days, 7 days, 30 days, 90 days - Last 6 months, 1 year The default range is **Last 30 days**. All panels on the dashboard update when you change the date range. ### Data Refresh Instead of waiting for the next scheduled sync to view the latest metrics, you can refresh the data in your dashboard any time by clicking **Refresh** at the top of the dashboard. The system updates the associated repos and sources, and the new status is displayed across all tabs, making it easy to track and confirm when the latest data is available. ### Repository Filter If the dashboard supports it, use the **Repositories** dropdown to filter data to specific repositories. You can select one or more repositories. When no filter is applied, the dashboard shows data across all repositories. ### Template Variables Some dashboards include additional filter controls (called template variables) at the top of the page. These vary by dashboard and may include dropdowns, interval selectors, or text inputs. Use them to refine the data shown in panels. ## Jira Dashboard The Jira dashboard visualizes issue and sprint data collected from your connected Jira projects. It works the same way as Git dashboards: Use the date range and variable filters at the top to refine what you see. Before data appears, you need at least one Jira project configured on the [Jira Connections](./jira-connections.md) page. The dashboard updates as data collection completes for each project. ## Empty States If you see a `No repositories found` message, it means the dashboard expects repository data that hasn't been collected yet. To resolve this, try the following steps: 1. Ensure you have [imported repositories](/docs/developer-portal/importing-repos) for the relevant Git provider. 2. Verify that [Development Insights is enabled](./development-insights.md#enabling-development-insights) in _Settings_. 3. Wait for data collection to complete. ## Troubleshooting | Situation | What to do | | ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | | Dashboard shows no data | Check that repositories have been imported and data collection is complete (status: _Synced_). | | A panel shows `Failed to load data` | Refresh the page. If the issue persists, the data source may be temporarily unavailable. | | Filters don't seem to work | Ensure you've selected at least one option and the date range covers the period you expect. | | Dashboard list is empty | Ask your administrator to [enable Development Insights](./development-insights.md#enabling-development-insights) in Settings. | | A panel type shows as `not supported` | This panel type hasn't been added to Venue.sh yet. The data is still being collected and will render when support is added. | --- ## Development Insights Development Insights brings engineering metrics directly into Venue.sh. It connects to your Git providers and Jira, visualizing commits, pull requests, contributor activity, and issue data through interactive dashboards. Once enabled, it automatically collects data from your imported repositories and Jira projects and presents it in ready-to-use dashboards. ## Key Features - **Ready-made dashboards** - Pre-built dashboards are created automatically when you enable the feature, giving you immediate visibility into engineering activity. - **Multi-provider support** - Works with GitHub, GitLab, Bitbucket, and Jira. Git data collection starts automatically when you import repositories. Jira data is collected by adding project keys through the [Jira Connections](./jira-connections.md) page. - **Interactive charts and filters** - Filter by repository, adjust the date range, and drill into stat panels, bar charts, time series, pie charts, and tables. - **Per-repository data collection** - Each imported repository gets its own data collection pipeline with status tracking. Failed collections can be retried from the UI. ## How It Works First, an admin or editor enables Development Insights in _Settings_. Venue.sh then provisions dashboards for the organization and begins syncing existing Git connections. When repositories are imported, data-collection pipelines are created automatically, and dashboards become available under _Development Insights_ in the sidebar. In summary, when you enable Development Insights and import repositories, Venue.sh: - Mirrors your Git connections to the data collection engine so it can authenticate with your Git provider. - Creates a data pipeline per repository that pulls commits, pull requests, and contributor information. - Populates dashboards with the collected data for you to explore. ## Enabling Development Insights :::info[Prerequisites] - An existing organization in Venue.sh - A role of Admin or Editor to enable the feature (though all roles can view dashboards once enabled) - At least one configured [Git connection](/docs/connections/git) ::: 1. In the Venue.sh app, click **Settings** in the sidebar. 2. In the **Organization** section, find **Development Insights**. 3. Toggle on **Enable Development Insights**. When you enable the feature for the first time: - Dashboards are created for your organization. - Existing Git connections are synced for metrics collection. - Repository imports will trigger data collection pipelines. - A new _Development Insights_ menu item appears in the sidebar. :::tip Enabling the Development Insights feature does not change your existing Git connections or repositories. It simply adds a data-collection layer on top of what you already have. ::: ### Disabling the feature You can disable Development Insights, via your settings, at any time by toggling off the feature. Disabling pauses data collection but preserves your dashboards and collected data. If you re-enable the feature later, everything picks up where it left off. ## Next Steps - **[Dashboards](./dashboards.md)** - Learn how to navigate dashboards, use filters, and understand the available panel types. - **[Jira Connections](./jira-connections.md)** - Connect Jira projects to start collecting issue and sprint data for your Jira dashboard. --- ## Jira Connections The _Jira Connections_ page lets you control which Jira projects are included in Development Insights data collection. Each Jira connection you have configured in Venue.sh appears here, and you can add project keys to start pulling issue and sprint data into your Jira dashboard. :::note[Prerequisites] The [Jira plugin](/docs/plugins/jira) must be enabled before Jira connections appear on this page. ::: ## Viewing Jira Connections 1. Click **Development Insights** in the sidebar. 2. Click the overflow menu (⋯) next to a Jira dashboard in the list, then select **Manage Connections**. Or navigate directly to **Development Insights > Jira Connections**. Each Jira connection is displayed as an expandable card, which shows: - **Connection URL** - The Jira instance the connection points to. - **Sync status** - The current state of the connection (e.g., _Synced_, _Syncing_, _Failed_). - **Project count** - How many Jira projects are currently configured for data collection. ## Adding a Jira Project Adding a project tells Venue.sh to start collecting issue and sprint data from that Jira project. 1. Expand the connection you want to configure. 2. Click **Add Project Key**. 3. In the dialog, search for and select a Jira project from the dropdown. The list is fetched live from your Jira instance. Projects already added to the connection are excluded. 4. Click **Add Project**. Data collection begins automatically once the project is added. The project appears in the connection's project table with a collection status that updates as data is synced. ## Collection Status Each project in a connection shows a collection status: | Status | Meaning | | --------- | ---------------------------------------------------------- | | _Synced_ | Data has been successfully collected. | | _Syncing_ | Data collection is in progress. | | _Failed_ | An error occurred during data collection. | | _Pending_ | The project has been added but collection has not started. | :::tip If a project shows a _Failed_ status, a retry button (↻) appears in the _Actions_ column. Click it to trigger a new collection run. ::: ## Troubleshooting | Situation | What to do | | ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | | No connections appear | Enable the Jira plugin in the _Plugins_ section, and ensure your Jira credentials are valid. | | A project doesn't appear in search | The project may not be accessible with the configured Jira credentials. Check permissions in your Jira account. | | Collection keeps failing | Click the retry (↻) button. If it continues to fail, ensure the Jira plugin credentials are still valid in _Settings_. | | Jira dashboard shows no data | Make sure at least one project has been added and its collection status is _Synced_. | --- ## Get Help Regardless of the issue, we're here to help! ## Create a Support Ticket Experiencing problems with Venue.sh? We can help! Submit a ticket through our [Support Portal](https://venuesh.atlassian.net/servicedesk/customer/portal/2 'Support Portal'). ## Make a Suggestion Do you have an idea to improve the app? [We'd love to hear from you!](https://venuesh.atlassian.net/servicedesk/customer/portal/2 'Support Portal') --- ## Getting Started Welcome to Venue.sh, your all-in-one developer portal! This document will guide you through the process of setting up and customizing your portal, covering key topics, tutorials, and best practices. ## Connecting Your Portal to Git To get started with [Venue.sh](https://venue.sh), you need to connect it to your preferred code versioning solution. This allows you to manage your repositories and track changes in real time. Follow these steps: 1. Log in to your Venue.sh dashboard and navigate to the Settings page. 2. Click on "Git Connections" and follow the [instructions](/docs/connections/git) to link your account. ## Configuring Plugins Venue.sh has a rich ecosystem of plugins that can enhance your portal's functionality. To configure plugins, follow these steps: 1. Navigate to the *Plugins* page in your Venue.sh dashboard. 2. Click on or search for the plugin you want to enable. 3. Follow the installation instructions for each plugin. See [Plugins](/docs/plugins) for more detailed instructions. ## Importing Repositories Once you've set up your [Git integration](/docs/connections/git) and [Plugins](/docs/plugins), it's time to import your projects. This allows you to customize metadata such as Team ownership, descriptions, tags and more for each repository. 1. Navigate to the Import page in your Venue.sh dashboard. 2. Select a Git provider you want to import from. 3. Select the repositories you want to import. 4. Customize the project metadata as desired. See [Importing Repos](/docs/developer-portal/importing-repos) for more detailed instructions. ## Next Steps Congratulations! You've completed the getting started guide for Venue.sh. Now that you have a solid foundation, here are some next steps to take: - **Create your first template** - Kickstart your self-service journey through [templates](/docs/developer-portal/templates). - **Explore our community resources** - Join the Venue.sh community Slack channel and engage with other users for support and knowledge sharing. --- ## Users and Teams Click **Users & Teams** in the upper-right corner of any app screen to access your venue settings. The _Users_ tab opens by default. ![Users and Teams button](../assets/users-and-teams-button.png) :::info - **Role-based dashboard view** - Your Venue dashboard and available actions will vary depending on your assigned role. For example, since users with the viewer role have no import permissions, import-related content does not appear on the viewer's dashboard. - Onboarding steps for new users also vary based on assigned role. See [RBAC](/docs/rbac) for more details on roles and permissions. ::: ## User Settings Admins and editors can manage user settings. (See [RBAC](/docs/rbac) for more info about roles and permissions.) Click the ellipses on the right side of a row to choose from the following user options: - **View profile** - Provides a summary of the user's information, including email address, a list of teams and roles, and activation status. Here you can activate/deactivate users, as well as permanently delete the selected user from the venue. - **Activate/Deactivate user** - Toggles a users activation status. This action is temporary and can be changed at any time. - **Delete user** - Permanently deletes a user from the venue. Deleted users must be reinvited to the venue to regain access. ### Inviting new users to your venue 1. On the _All Users_ tab, click **Invite user** to invite a new person to your venue. 2. On the _Invite user_ screen, enter their email address and role. 3. Optional: Select a team for the invitee. 4. Click **Send invite**. An invitation to the venue will be sent to the provided email address. Use the _Invited Users_ tab to monitor invitation requests. ## Team Settings Admins and editors can manage team settings. (See [RBAC](/docs/rbac) for more info about roles and permissions.) Click the ellipses on the right side of a row to choose from the following user options: - **View team** - Provides a summary of a team, including name, description, list of team members, and more. Here you can manage (add or remove) team members, join the team yourself, permanently leave a team, or permanently delete a team. - **Manage users** - Allows you to add or remove users from an existing team. - **Delete team** - Permanently deletes a team from the venue. ### Creating a new team 1. On the _Teams_ tab, click **New team**. 2. On the _Create a new team_ dialog, enter the team name and team description. 3. Optional: Add existing venue users to the new team. :::tip As the team creator, you will not be added to the team automatically; you must be manually added like any new user. ::: 4. Click **Create team**. --- ## Overview [Venue.sh](https://venue.sh) is an Internal Developer Portal (IDP) with a UX focus, empowering teams to streamline their development, delivery, and collaboration processes, freeing them to focus on the things that really matter. ## Venue.sh Offerings - **Developer Portal and Software Catalog** - Connect Git providers, import repositories, model entities, and establish clear service ownership in one place. - **Self-Service Templates** - Bootstrap new services with tested templates, or create custom templates tailored to your engineering standards. - **Development Insights** - Track engineering activity with ready-made dashboards for commits, pull requests, contributors, throughout your CI/CD pipeline. - **Scorecards** - Enforce quality and compliance with rule-based validation for metadata, specifications, and integration annotations. - **Assistant, Agents, MCP, and Skills** - Use AI in the Venue.sh portal to query catalog, docs, templates, and plugin data. Define organization-scoped agents with custom instructions and capability bindings, index repositories for summaries and code-aware Assistant answers, connect external MCP-enabled tools (_e.g.,_ Cursor and Claude Desktop) to Venue's MCP endpoint, register MCP servers in the catalog, and browse agent skills discovered from connected repositories. - **Plugin Ecosystem** - Extend Venue.sh with integrations across delivery, observability, security, and collaboration tooling. - **RBAC and Activity Log** - Manage access with role-based permissions and maintain audit visibility with searchable activity history and exports. ## Why Teams Use It Venue.sh improves developer experience while giving platform teams stronger governance: - **Higher visibility** across services, owners, repositories, and engineering activity - **Faster delivery** through self-service workflows and reusable templates - **Stronger standards** with scorecards, role-based access, and audit trails - **Better decision-making** with consolidated metrics and integration data Get started by creating your account and venue at [Venue.sh](https://dashboard.venue.sh/sign-up). It only takes a few minutes to explore the platform. --- ## Argo CD Plugin The Argo CD plugin allows users to view the sync status, health status, and deployment history of Argo CD applications within Backstage entities. The Argo CD plugin supports multiple Argo CD instances, allowing teams to manage different environments or clusters from a single interface. :::note The current version of the plugin supports only one instance, but future work will enable the ability to view multiple instances. ::: ## Generating Credentials To configure the Argo CD plugin in Venue.sh, you must create a user token in Argo CD. 1. Log into Argo CD. 2. Navigate to **Settings > Accounts**. A full list of Argo CD user accounts appears. 3. Select the user account you want to connect to Venue.sh. 4. In the _Tokens_ section, create a **Token ID**. Token IDs appear in Venue.sh and help differentiate among multiple Argo CD tokens in a single venue. :::tip You can also define an expiration date for the token, though it's optional. ::: 5. Click **Generate New** and confirm the new-token creation when prompted. The new token appears in the _Tokens_ section. 6. Copy the new token and proceed to configure the Argo CD plugin in Venue.sh. ## Configuring the Argo CD Plugin in Venue.sh 1. In the Venue.sh app, click **Plugins** in the left-side navigation. 2. Find Argo CD, then click **Enable Plugin**. 3. Complete the following fields: - **Auth Token**: This token is generated in Argo CD in the settings of the desired Argo CD user account or via the CLI. See the [Generating Credentials](#generating-credentials) section directly above for step-by-step instructions on creating new tokens. - **Instance URL**: The base URL for your Argo CD instance. 4. Click **Enable**. ## Component Setup There are two ways to connect an Argo CD application a `dashboard` component. :::info[Prerequisite] Enable the Argo CD plugin in Venue.sh. ::: - Edit an existing `dashboard` component, toggle on additional Argo CD metadata fields, then add your desired Argo CD application name. - If you're importing a new repo as a component, connect an Argo CD appliction by toggling on the Argo CD metadata fields and adding a specific Argo CD application name. --- ## Artifactory Plugin The Artifactory plugin allows users to associate a Venue.sh entity with one Artifactory Docker Registry and view the Docker images in the registry. :::note Venue.sh supports both Cloud and On-Prem versions of Artifactory. ::: ## Configuring the Artifactory Plugin in Venue.sh 1. In the Venue.sh app, click **Plugins** in the left-side navigation. 2. Find Artifactory, then click **Enable Plugin**. 3. Enter the **Artifactory URL** value, which is the base URL of your Artifactory instance. 4. Enter the **Artifactory Token** value, which is the token from your Artifactory instance. 5. Click **Validate & Enable**. Once the changes save to the database, Artifactory is added to the _Optional metadata_ options. Click **Toggle optional fields**, then select **Artifactory** to show the **Artifactory Component Name** field. Add the registry name to the field, and the _JFrog Artifactory_ tab displays when viewing the component. --- ## AWS Cost Insights Plugin The AWS Cost Insights plugin integrates AWS Cost Explorer data directly into your Venue portal. This plugin enables engineering teams to visualize and understand their AWS spending patterns at service and component levels, providing crucial insights for cost optimization and budget management. ## AWS Configuration This configuration deals with AWS users, roles, and policies. While you can create each of these in whichever order you like, we recommend creating a policy first, and then attaching that policy to both roles and users. :::info[Prerequisites] Log in to your desired AWS account, and click the **IAM** (Identity and Access Management) service. ::: 1. Create a new policy. 1. Click the **Policies** in the lefthand navigation options. 2. Click **Create policy**. 3. Name the new policy something like `VenueInsightsPolicy`. 4. Add your desired permissions to the policy, including allowances for Cost Explorer Service (full access), IAM service (Limited: List, Read), and Organizations (Limited: List, Read). 2. Create a new user. 1. Click the **Users** in the lefthand navigation options. 2. Click **New user**. 3. Name the new user something like `costinsights-user`. 4. Search for and assign the policy you created in Step 1 to the new user. 5. Click the **Security Credentials** tab, then click **Create access key** for a new user. :::tip Note and save the Access Key and Secret Key, which you'll use later in Venue.sh. ::: 3. Create a new role. 1. Click the **Roles** in the lefthand navigation options. 2. Click **Create role**. 3. Name the new user something like `VenueCostInsightsRole`. 4. Search for and assign the policy you created in Step 1 to the new role. 4. Add a trust policy for the new role to assume the newly created user. 1. Navigate to the new role created in Step 3. 2. Click the **Trust Relationships** tab. 3. Add the following trust policy with your desired user detail: ````{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::0123456789012:" }, "Action": "sts:AssumeRole", "Condition": {} } ] }``` ```` 5. Permit the new user to assume the newly created role. 1. Navigate to the new user created in Step 2. 2. In the _Permissions policies_ section, click the role you created in Step 3 to open the permissions editor. 3. In the editor, add the following permissions update with your desired role detail: ````{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": "sts:AssumeRole", "Resource": "arn:aws:iam::0123456789012:role/" } ] }``` ```` Next, proceed to the next section to configure the AWS Cost Insights plugin in Venue.sh. ## Configuring the AWS Cost Insights Plugin in Venue.sh :::info[Prerequisites] Log in to your desired AWS account in a separate tab or window. You may need to locate and retrieve information to configure the plugin. ::: 1. In the Venue.sh app, click **Plugins** in the left-side navigation. 2. Find AWS Cost Insights, then click **Enable Plugin**. 3. Enter the **AWS Access Key ID** value. You should have noted and saved this value in Step 2.v in the AWS-configuration task above. 4. Enter the **AWS Secret Access Key** value. You should have noted and saved this value in Step 2.v in the AWS-configuration task above. 5. Enter the **AWS Region** value for the region in which you've enabled AWS Cost Insights. In AWS, the geographic region (or `Global` if not region-specific) is listed in the banner at the top of the screen. 6. Enter the **AWS Account ID** value. In AWS, the Account ID value is in the upper-right corner of the screen. Click the ID to view a drop-down list of options, then click **copy** for the **Account ID**. 7. Enter the **AWS Role Name** value. This role name was created in Step 3 in the AWS-configuration task above. 8. Click **Validate & Enable**. Once the changes save to the database, a new _Cost Insights_ tab appears on the component page, from which you can view cost details. :::tip You can also get cost details about AWS resources by using AWS tags in Venue.sh. If you want to inquire on the cost of a resource, simply add the resource tag from AWS to the entity in your portal when you either import or edit an entity. ![AWS resource tags](../assets/aws-tags.png) ::: --- ## Confluence Plugin To use the Confluence plugin, Venue.sh requires an API token to communicate with Confluence APIs. This document outlines the process of creating the API token and configuring the plugin. ### Generating an API Token To generate a personal access token for Confluence Cloud, follow these steps: 1. **Log in to your Atlassian account**: - Go to [Atlassian Cloud](https://id.atlassian.com/manage-profile/security/api-tokens). 2. **Navigate to the API Tokens page**: - Once logged in, click on your profile picture or avatar at the bottom left corner. - Select **Account settings** from the dropdown menu. - In the left-hand sidebar, click on **Security**. - Under **API tokens**, click on **Create API token**. 3. **Create a new API token**: - Click the **Create API token** button. - Enter a label for your token, such as `Venue.sh Token`. - Click **Create**. 4. **Copy your API token**: - Click **Copy to clipboard** to save the token. - **Important**: Save this token in a secure place. You won't be able to see it again! To generate a personal access token for Confluence Data Center, follow these steps: 1. **Log in to Confluence Data Center**: - Open your Confluence DC instance and log in with your account. 2. **Navigate to Personal Access Tokens**: - Click on your profile picture or avatar at the top right corner. - Select **Settings** from the dropdown menu. - In the left-hand sidebar, find and click on **Personal Access Tokens**. 3. **Generate a new token**: - Click on **Create a personal access token**. - Fill in the details for the token: - **Name**: Give your token a descriptive name, such as `Venue.sh Token`. - **Expiry Date**: Optionally, set an expiry date for your token. - **Permissions**: Choose the appropriate permissions required for the token. - Click **Create**. 4. **Copy your personal access token**: - Your new token will be displayed. Click **Copy to clipboard** to save the token. - **Important**: Save this token in a secure place. You won't be able to see it again! ### Configuration To enable and configure the Confluence plugin, you need to provide several key details. Follow the instructions below to complete the setup. 1. **Confluence URL** - For Confluence Cloud: `` **`/wiki`** - e.g. `https://.atlassian.net/wiki` - For Confluence Data Center (DC): `` - e.g. `https://confluence.yourcompany.com` 2. **Space Keys**: - Provide the keys for the Confluence spaces you want to access. Space keys are unique identifiers for Confluence spaces. - e.g. - `Development` - `Marketing` - Add one space key per line, using the add button if more items are needed. 3. **Instance Type**: - Select the type of Confluence instance you are using. - Confluence Cloud - Enter the email address associated with the Confluence user account. - Enter the API token generated in the previous step. - Confluence Data Center (DC) - Enter the API token generated in the previous step. Following these steps will ensure that the plugin is correctly configured to interact with your Confluence instance. Make sure to keep your API token secure and do not share it publicly. ## Learn More Looking for more information? Check out the following resource: - [Atlassian docs for creating API tokens](https://support.atlassian.com/atlassian-account/docs/manage-api-tokens-for-your-atlassian-account/) --- ## Datadog Plugin The Datadog plugin integrates Datadog dashboards directly into your Venue portal and enables teams to visualize and monitor databases, tools, performance metrics, logs, and dashboards without leaving Venue.sh. ## Preconfiguration: Gathering Necessary Data To use the Datadog plugin in Venue.sh, you first need to gather the following information from your Datadog account: 1. Retrieve the URLs of the Datadog dashboards you want to display in Venue.sh. 1. Login to your Datadog account and navigate to your dashboard list. 2. Select the dashboard you want to embed from the dashboard list. 3. Open sharing settings by clicking the Settings cog icon on the right side of the dashboard. 4. Copy the public URL, which allows public access to your dashboard, from the sharing textbox. Example: `https://app.datadoghq.com/dashboard/abc-def-ghi` 5. Save the URL for later configuration steps in Venue.sh. 2. Retrieve your Datadog site region from your Datadog URL. :::tip Common region values include: - `datadoghq.com` (US1) - `datadoghq.eu` (EU1) - `us3.datadoghq.com` (US3) - `us5.datadoghq.com` (US5) - `ap1.datadoghq.com` (AP1) ::: ## Enabling the Datadog Plugin in Venue.sh 1. In the Venue.sh app, click **Plugins** in the left-side navigation. 2. Find Datadog, then click **Enable Plugin**. ## Displaying Datadog Dashboards in Venue.sh (New Entities) Follow these steps to display your Datadog dashboards in Venue.sh, as you import entities for the first time. 1. In Venue.sh, click **Import** on the left-hand navigation panel. 2. Choose a connection, select the entities you want to track as components in your Catalog, then click **Next Step**. 3. Click **Configure optional fields**, and select **Datadog**. 4. Configure your import. 5. Add the values you gathered in the preconfiguration steps (above) for **Datadog Dashboard URL(s)** and **Datadog Site**. 6. Complete the import process. 7. Click **Catalog** in the left-hand navigation panel. 8. Select your entity. 9. Click the **Datadog** tab to view your embedded dashboard(s). ## Displaying Datadog Dashboards in Venue.sh (Existing Entities) 1. Click **Catalog** in the left-hand navigation panel. 2. Locate and select the entity you want to add Datadog dashboards to. 3. Click **Edit**. 4. In the edit form, scroll to the _Optional metadata_ section and click **Toggle optional fields**. 5. Select **Datadog** from the available optional fields, then enter the values you gathered in the preconfiguration steps (above) for **Datadog Dashboard URL(s)** and **Datadog Site**.. 6. Click **Save** changes to apply the changes. 7. Navigate back to your entity in the Catalog. 8. Click the **Datadog** tab to view your embedded dashboard(s). ## Viewing Your Datadog Configuration 1. Click **Catalog** in the left-hand navigation panel. 2. Locate and select the entity you configured. 3. While on the _Overview_ tab, click the **overflow** menu (three dots), and select **Inspect entity**. The _Entity Inspector_ window appears. 4. Scroll down to the _Metadata_ section, and look for the following annotations: - `datadoghq.com/dashboard-url` - Your dashboard URL(s) - `datadoghq.com/site` - Your Datadog site region --- ## Development Containers Plugin This plugin allows users to automatically launch fully-contained development environments with [development containers (dev containers)](https://containers.dev/). The Dev Containers plugin is permanently enabled in a customer’s Venue. ## Configuration There are no required or optional configuration values for this plugin. It is enabled permanently and cannot be disabled. Using the plugin is as simple as importing an entity (repository) that contains a `devcontainers.json` file. Once imported, a notice appears on the _Entity Overview_ page. ![Dev Containers plugin card](../assets/dev-containers-plugin-card.png) And the plugin automatically adds the dev-containers tag to the entity, if applicable. ![dev-containers tag](../assets/dev-containers-tag.png) The Venue.sh team recommends using Dev Containers with VS Code's [Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers). ### Limitations - The repository URL must end in `catalog-info.yaml` - The `devcontainers.json` file must be located in one of the directories specified by the [official Dev Containers documentation](https://containers.dev/implementors/spec/#devcontainerjson), which include the following: - `.devcontainer/devcontainer.json` - `.devcontainer.json` - `.devcontainer/folder/devcontainer.json` (sub folder, one level deep) ### Example The example that follows is a `devcontainer.json` used to start a development environment with the `terraform:1.9` container. [View the full specification](https://containers.dev/implementors/json_schema/). ```json // For format details, see https://aka.ms/devcontainer.json. For config options, see the // README at: https://github.com/devcontainers/templates/tree/main/src { "name": "terraform:1.9", // Or use a Dockerfile or Docker Compose file. More info: https://containers.dev/guide/dockerfile "image": "public.ecr.aws/hashicorp/terraform:1.9", // Features to add to the dev container. More info: https://containers.dev/features. "features": {}, // Use 'forwardPorts' to make a list of ports inside the container available locally. // "forwardPorts": [3000], // Use 'postCreateCommand' to run commands after the container is created. // "postCreateCommand": "uname -a", // Configure tool-specific properties. "customizations": { "vscode": { "extensions": ["hashicorp.terraform", "redhat.vscode-yaml"] } } // Uncomment to connect as root instead. More info: https://aka.ms/dev-containers-non-root. // "remoteUser": "root" } ``` --- ## Jenkins Plugin The Jenkins plugin allows users to associate an entity with one or more Jenkins jobs. Users can easily view the status of current builds linked or related to the entity. The plugin also provides direct access to Jenkins, allowing users to open and run specific jobs from there directly. ## Configuring the Jenkins Plugin in Venue.sh 1. In the Venue.sh app, click **Plugins** in the left-side navigation. 2. Find Jenkins, then click **Enable Plugin**. 3. Enter the **Base URL** value for the Jenkins instance. 4. Enter the **Username** value, which is the username used to log into Jenkins. 5. Enter the **API Key** value. :::tip To generate an API key in Jenkins: 1. Log in to Jenkins as an administrator. 2. Navigate to **Manage Jenkins > Manage Users.** 3. Select a user to generate an API key for. 4. On the configuration page, click **Add new token.** 5. Copy the new API token. 6. Click save. ::: 6. Click **Validate & Enable**. ## Using Jenkins in the Venue.sh Catalog Once the Jenkins plugin is configured and enabled in Venue.sh, follow these steps to edit an existing catalog entry to enable Jenkins jobs: 1. Navigate to the Catalog, and select a component to edit. 2. In the component _About_ section, click **Edit**. 3. In the _Optional metadata_ section, click **Toggle optional fields**, then select **Jenkins**. The **Jenkins Job Full Name** text bar appears on the screen. 4. Add a valid Jenkins job in the text box. :::note You can add multiple Jenkins jobs if separated by a comma. ::: 5. Click **Save changes**. Once the changes save to the database, a new _Jenkins_ tab appears on the component page, from which you can view build details. --- ## Jira Plugin To use the Jira plugin, Venue.sh requires an API token to communicate with Jira APIs. This document outlines the process of creating and setting up the API token. ## Generating an API Token 1. Navigate to the user profile settings page for your Jira account: [Jira API Tokens](https://id.atlassian.com/manage-profile/security/api-tokens). :::tip We suggest creating a dedicated automation/bot account for API usage. ::: 2. Click **Create Classic API Token**. 3. In the _Create an API Token_ modal, name the token "Venue.sh" to easily identify it later. 4. Click **Create.** The new API token appears on the screen. 5. Copy and save the token in a secure location. :::tip Atlassian displays the API token only once, so make sure you save it in a secure place. You won't be able to see it again! ::: ## Configuring the Jira Plugin in Venue.sh To configure the Jira plugin in Venue.sh, follow these steps. 1. In the Venue.sh app, click **Plugins** in the left-side navigation. 2. Find Jira, then click **Enable Plugin**. 3. On the configuration modal, enter the values for the following three fields: - **Target**: Your Jira Cloud domain (e.g. `https://venuesh.atlassian.net`) - **Authorization**: Your Base64-encoded string for your email/Jira token. 1. First, format your email address and Jira token as follows: ``` : email@example.com:9bljDpJKRev44C3z ``` 2. Next, convert your `email:Jira token` to Base64. :::tip [Here's a shortcut to CyberChef](), a tool that helps you quickly encode text to Base64. ::: 3. Add "Basic" to the front of your new Base64 string, which will look similar to this: Example: `Basic Y29vbHBwbFJraW5kQG1haWwuY29tOmpkYWg4a2RqdzlhMjJzcw==` 4. Add this Base64 string to the **Authorization** field. - **User-Agent**: Enter "Mozilla/5.0" ## Component setup Within your component catalog-info.yaml file, add the following annotations to connect your Jira project: ```yaml metadata: annotations: jira/project-key: [YOUR_PROJECT_KEY] jira/component: [YOUR_COMPONENT] ``` :::tip You can skip the `jira/component` line to fetch data for all components across multiple Jira projects. ::: ## References Looking for more information? Check out the following resource: - [Atlassian docs for creating API tokens](https://support.atlassian.com/atlassian-account/docs/manage-api-tokens-for-your-atlassian-account/) --- ## Kubernetes Plugin The Kubernetes plugin for Backstage extends the core Backstage Developer Portal by integrating Kubernetes information directly into your entities. It provides a unified view of Kubernetes workloads across clusters, enabling service owners to monitor the health of their services without switching contexts. With the Kubernetes plugin, you can: - **Visualise deployments across clusters:** The plugin aggregates pods, deployments, and ReplicaSets from multiple clusters into a single view. This means you can see all your service's deployments in one place instead of switching kubectl contexts. - **Receive automatic error reports:** The plugin highlights errors in Kubernetes resources so you can see failing pods or deployments without running multiple commands. - **Review autoscaling insights:** The UI shows how close your service is to its autoscaling limit across clusters, helping you prepare for load spikes. - **Cloud‑agnostic:** Because the plugin calls the Kubernetes API directly, it works the same whether you deploy on AWS, Azure, Google Cloud, OpenShift or any other platform. - **Improve your developer experience:** By surfacing Kubernetes data inside the Venue Dashboard catalog, the plugin helps reduce the infrastructure complexity developers face. You can monitor deployments, view cluster health and troubleshoot issues without leaving Venue, unless you absolutely need to. ## Required Configuration To connect with the Kubernetes plugin, you need to define at least one cluster in the plugin settings. Each cluster must provide the following fields: | Field | Required | Description | | ---------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Cluster URL** | ✅ | The base URL of the Kubernetes API server. You can obtain this by running `kubectl cluster-info` against the target cluster. The plugin uses this URL to query pods, services, and other resources. | | **Cluster Name** | ✅ | A unique name for the cluster. This name is referenced in entity annotations when selecting clusters. | | **Service Account Token** | ✅ | A bearer token is used to authenticate to the cluster. To retrieve it, create a [ServiceAccount](https://kubernetes.io/docs/concepts/security/service-accounts/) with read‑only privileges and extract its token. See the note below for additional details. | | **CA Data (Base64 encoded)** | ✅ | The base64‑encoded certificate authority data for the cluster, which allows the plugin to verify the cluster’s TLS certificate.. You can copy the `certificate-authority-data` value from your `~/.kube/config` file or run `kubectl config view --raw --minify` and extract the `certificate-authority-data`. | | **Dashboard URL** | ❌ | (Optional) The URL of the Kubernetes Dashboard for your cluster. This must be a valid HTTP or HTTPS URL, which the plugin validates before saving. If provided, the plugin will be linked directly to the dashboard UI. | :::note The service account you provide must have at least read-only access to pods, services, configmaps, deployments, replicasets, horizontalpodautoscalers (HPA) and ingresses. Without these permissions, the plugin cannot display cluster resources. Kubernetes v1.21+ transitioned from static, never-expiring service account tokens to short-lived "bound" tokens issued through the TokenRequest API. These bound tokens expire when the pod is deleted or after a set duration—defaulting to one hour—and the kubelet refreshes them automatically. The plugin reads the cluster from outside Kubernetes and cannot rely on the kubelet to refresh a bound token, so an hourly expiry would force you to manually rotate the token every hour. Kubernetes still supports issuing a long‑lived token by creating a `Secret` of type `kubernetes.io/service-account-token`. For more information on how to do this, see the [Kubernetes documentation](https://kubernetes.io/docs/tasks/configure-pod-container/configure-service-account/#manually-create-a-long-lived-api-token-for-a-serviceaccount). ::: ## Entity Configuration Once a cluster is configured, tell the plugin which Kubernetes resources belong to a particular service by adding one or more of the following annotations to your component: | Reference | Description | | ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Kubernetes ID | A unique identifier that links an entity to Kubernetes resources. Add this annotation to the entity and add the same label (kubernetes-id) on your Kubernetes resources. | | Kubernetes label selector | A comma-separated list of key=value pairs used to select resources, e.g., `app=my-app,component=front-end`. The plugin uses this selector to find objects in the cluster. | | Kubernetes cluster name | When using the `singleTenant` service locator, specify the name of the cluster (matching the `cluster name` in the plugin configuration) to limit resource lookup to that cluster. | | Kubernetes namespace | (Optional) Overrides the namespace used when retrieving resources. This can be helpful if your service runs in a specific namespace. | The Venue.sh plugin enforces that a cluster name is specified and at least one of `kubernetes-id` or `kubernetes-label-selector` must be present. If you omit the namespace annotation, the plugin defaults to searching all namespaces. Once this has been configured, the _Kubernetes_ tab will become visible on your entity. ![Kubernetes tab](../assets/kubernetes-tab.png) --- ## LaunchDarkly Plugin The LaunchDarkly plugin integrates feature flag management directly into your Venue portal, allowing teams to view and monitor the state of feature flags for their services without leaving Venue.sh. ## Preconfiguration: Generating an API Token To use the LaunchDarkly plugin in Venue.sh, you need a LaunchDarkly API access token with read access. 1. Log in to your LaunchDarkly account, and navigate to **Account Settings > Authorization**. 2. Click **+ Token** in the _Access tokens_ section. 3. Give the token a name (e.g., `venue-sh`), and set the role to **Reader**. 4. Click **Save token**. 5. Copy and save the token in a secure location. :::tip LaunchDarkly displays the token only once. Make sure you save it before closing the dialog! ::: ## Configuring the LaunchDarkly Plugin in Venue.sh 1. In the Venue.sh app, click **Plugins** in the left-side navigation. 2. Find LaunchDarkly, then click **Enable Plugin**. 3. On the configuration modal, enter your **LaunchDarkly API Token** (generated above). 4. Click **Save Changes**. ## Component Setup Add the following annotations to your entity's `catalog-info.yaml` file to connect it to the relevant LaunchDarkly project and environment: ```yaml metadata: annotations: launchdarkly.com/project-key: [YOUR_PROJECT_KEY] launchdarkly.com/environment-key: [YOUR_ENVIRONMENT_KEY] ``` :::tip - **Project key** - Found in your LaunchDarkly dashboard under **Account Settings > Projects**. It is the short identifier (e.g., `my-project`). - **Environment key** - Found within a project's settings (e.g., `production`, `staging`). ::: Once configured, navigate to your entity in the Catalog, and click the **LaunchDarkly** tab to view the feature flags associated with that service. ## Viewing Feature Flags The LaunchDarkly tab displays two sections, _Project Overview_ and _Context Overview_. ### Project Overview A table of all feature flags in the linked LaunchDarkly project, showing: - **Name** - The flag name - **Maintainer** - The user responsible for the flag - **Kind** - The flag type (e.g., `boolean`, `multivariate`, etc.) - **Created** - Date the flag was created - **Version** - The current flag version ### Context Overview A detailed breakdown of each flag for the linked environment, showing: - **Name / Key** - The flag name and its unique key - **Description** - An optional description of the flag's purpose - **Status** - Whether the flag is currently enabled or disabled - **Tags** - Any tags associated with the flag - **Variations** - The individual variations and their enabled/disabled state Expanding a flag also shows environment-targeting details for each environment in your LaunchDarkly project. Details include context targets, fallthrough variation, off variation, version, last modified date, and whether event-tracking is enabled. ## Learn More Looking for more information? Check out the following resources: - [LaunchDarkly docs: Creating API access tokens](https://docs.launchdarkly.com/home/account/api) - [LaunchDarkly docs: Projects](https://docs.launchdarkly.com/home/organize/projects) - [LaunchDarkly docs: Environments](https://docs.launchdarkly.com/home/organize/environments) --- ## Nexus Repository Manager Plugin The Nexus Repository Manager plugin allows engineers to surface build artifact and repository information directly within their Backstage entities. The plugin pulls data from Nexus and displays it contextually on the entity page, enabling teams to quickly locate, review, and validate stored artifacts without leaving Backstage. With this plugin, users can: - View build artifacts stored in Nexus repositories in a dedicated _Build Artifacts_ tab on the entity page. - Access repository metadata and artifact details without navigating to the Nexus web interface. - Link components in the Backstage catalog to Nexus repositories. ## Configuring the Nexus Plugin in Venue.sh To connect Nexus to Venue.sh, the following fields must be configured: | Field | Required | Description | | ------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Nexus Target URL** | ✅ | Base URL for the Nexus instance (e.g., `nexus.domain.com`). | | **Authorization (Base64)** | ✅ | Base64-encoded `user:pass` string for Nexus authentication. To locate, go to **Nexus Settings > User Token > Access User Token**, and copy the Base64 representation of `user:password`. | | **Target or Project Reference** | ✅ | You must provide one of the following to identify the Nexus artifact data to display for each entity: **Docker entity** `nexus-repository-manager/docker.image-name`: Docker image name in Nexus, e.g., `group/artifact-name`To locate, find the asset within Nexus and copy the component name, including the group name and asset (e.g., `bitnami/redis-cluster`). **Other entities (experimental)** `nexus-repository-manager/repository`: The Nexus repository name, e.g., `releases` `nexus-repository-manager/name`: The specific artifact name, e.g., `my-service-api`To locate, find the asset within Nexus and copy the repository name (e.g., `bitnami-helm`) and component name (e.g., `redis-cluster`). | Follow these steps to configure the Nexus plugin: 1. In the Venue.sh app, click **Plugins** in the left-side navigation. 2. Find Nexus Repository Manager, then click **Enable Plugin**. 3. Enter the **Nexus Target URL** value. 4. Enter the **Authorization (Base64)** value. 5. Click **Enable**. ## Nexus References (Entity YAML) Once enabled, the following references are available: | Reference | Description | | -------------------------------------------- | -------------------------------------------------------- | | `nexus-repository-manager/docker.image-name` | Docker image name in Nexus, e.g., `group/artifact-name`. | | `repository` | The Nexus repository name. | | `name` | The specific artifact name. | --- ## PagerDuty Plugin The PagerDuty plugin provides real-time incident visibility and management capabilities directly within Backstage entities, allowing teams to: - View active and recent incidents - Track incident status changes - Access PagerDuty service metrics - Connect directly to PagerDuty for deeper incident management ## PagerDuty OAuth App Setup Follow these steps to register an OAuth app in the PagerDuty dashboard. 1. Log in to your PagerDuty account. 2. From the top menu, select **Integrations**. 3. Under _Developer Tools_, select **App Registration**. This opens the _My Apps_ page. 4. On the _My Apps_ page, select **New App**. The _Add New App_ dialog opens. 5. Enter a name and description for your app. 6. In the _Functionality_ section, select **OAuth 2.0**, then click **Next**. 7. Select **Scoped OAuth** as the preferred authorization mechanism. 8. Select the following permissions, then click **Register App**: - abilities.read (used in scaffolder only) - analytics.read - escalation_policies.read - incidents.read - oncalls.read - schedules.read - services.read - services.write (used in scaffolder only) - standards.read - teams.read - users.read - vendors.read (used in scaffolder only) 9. Copy the Client ID and Client Secret values, and store them somewhere safe. You will use them later to configure the plugin in Venue.sh. ## Annotating Entities To link entities with specific PagerDuty services, be sure to add the `service-id` when you import an entity: ```yaml annotations: pagerduty.com/service-id: [SERVICE-ID] ``` You can find the service ID by navigating to a service with a PagerDuty console and pulling the ID value out of the URL. For example: https://[YOUR-ACCOUNT].pagerduty.com/service-directory/[SERVICE-ID]. ## Configuring the PagerDuty Plugin in Venue.sh 1. In the Venue.sh app, click **Plugins** in the left-side navigation. 2. Find PagerDuty, then click **Enable Plugin**. 3. Enter the **Client ID** value. You should have noted and saved this value in Step 9 in the PagerDuty-configuration task above. 4. Enter the **Client Secret**. You should have noted and saved this value in Step 9 in the PagerDuty-configuration task above. 5. Enter your PagerDuty **Subdomain** value. 6. Optional: Enter a **Region** value, either `us` (default) or `eu` to reflect the location of your PagerDuty instance. 7. Click **Validate & Enable**. --- ## Plugins Plugins are extensions that enhance the functionality of the Developer Platform, allowing you to integrate a wide variety of tools, services, and custom features into your instance. These plugins are designed to be modular and easy to install, enabling you to tailor the platform to the specific needs of your organization. ## Wide Range of Integrations Plugins cover a wide array of integrations, including but not limited to: - **CI/CD Tools** - Jenkins, GitHub Actions, CircleCI, and more. - **Monitoring and Logging** - Prometheus, Grafana, ELK stack. - **Documentation** - TechDocs, Markdown support. ## Easy Installation and Configuration Plugins can be easily installed and configured through the _Plugins_ menu on the dashboard sidebar. ## Conclusion Plugins are a powerful way to extend the capabilities of your instance, integrating essential tools and services into a unified developer platform. Plugins help streamline workflows, improve visibility, and enhance productivity across your organization. --- ## ServiceNow Plugin The ServiceNow plugin connects Venue.sh components to ServiceNow incident tickets. It maps Backstage entities to ServiceNow records using the `servicenow.com/entity-id` annotation. ## Prerequisites Before enabling the plugin, make sure you have: - A ServiceNow instance URL (for example: `https://my-company.service-now.com`) - A ServiceNow OAuth client (`clientId` and `clientSecret`) - A ServiceNow integration user (`username` and `password`) :::note This integration uses the OAuth `password` grant type. For token endpoints, grant types, and request parameter details, see ServiceNow’s [OAuth API request parameters](https://www.servicenow.com/docs/r/platform-security/authentication/r_OAuthAPIRequestParameters.html) documentation. ::: ## Create ServiceNow OAuth Credentials In ServiceNow, create an OAuth application for external clients and collect the credentials required by Venue.sh. 1. Open **System OAuth > Application Registry**. 2. Click **New**. 3. Select **Create an OAuth API endpoint for external clients**. 4. Complete the form and save. 5. Copy the generated **Client ID** and **Client Secret**. 6. Confirm the integration user account (username/password) that Venue.sh should use. ## Configure the ServiceNow Plugin in Venue.sh 1. In Venue.sh, click **Plugins** in the left-side navigation. 2. Find **ServiceNow**, then click **Enable Plugin**. 3. Complete the plugin form: - **Instance URL**: The base URL of your ServiceNow instance. (Example: `https://my-company.service-now.com`) - **OAuth Grant Type**: Automatically set to `password`. - **Client ID**: The OAuth client ID from ServiceNow. - **Client Secret**: The OAuth client secret from ServiceNow. - **Username**: ServiceNow username for the integration account. - **Password**: ServiceNow password for the integration account. 4. Click **Enable**. ## Component Setup Add the following annotation to your component `catalog-info.yaml`: ```yaml metadata: annotations: servicenow.com/entity-id: [YOUR_ENTITY_ID] ``` :::tip The annotation value must match the **u_backstage_entity_id** field used in your ServiceNow incident records. ::: ## Validation Rules Venue.sh validates the plugin configuration as follows: - `instanceUrl` must be a valid URL - `instanceUrl` must match the ServiceNow domain pattern (`*.service-now.com`) - All OAuth fields are required: `clientId`, `clientSecret`, `username`, and `password` ## References To learn more, see [OAuth API request parameters](https://www.servicenow.com/docs/r/platform-security/authentication/r_OAuthAPIRequestParameters.html), the official ServiceNow documentation for OAuth setup, which includes additional info on grant types, endpoints, parameters, and more. --- ## Snyk Plugin The Snyk plugin allows engineers to surface application security issues directly within their Backstage entities. It pulls vulnerability data from Snyk and displays it contextually in two key locations on the entity page, allowing teams to stay informed and take action faster. :::note This plugin is available for Snyk Enterprise users only, as it requires access to organization-level API capabilities. Please contact Snyk to confirm whether your organization plan includes the required API access. ::: ## Basic functionality The Snyk plugin allows you to: - View detailed vulnerabilities in the _Snyk_ tab on the entity page, helping teams assess security risks linked to their services. - Get a quick snapshot of security issues using the Snyk overview widget, which displays a compact count of vulnerabilities directly on the entity overview page. - Connect one or more Snyk organisations to Backstage and link relevant projects or targets to entities using those references. - Monitor the health and security of services directly in Backstage, without switching tools. ### Notable fields To connect Snyk to Venue.sh via the plugin settings, the following fields must be configured: | Field | Required | Description | | ------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **API URL** | ✅ | Use the correct base URL for your region (see below) | | **Auth Token** | ✅ | Generated from your Snyk account (**Account Settings > API Token**). The auth token must be re-entered if the plugin settings are changed. | | **Org ID** | ✅ | At least one Snyk organisation must be specified using `snyk.io/org-id` or `snyk.io/org-ids` | | **Target or Project Reference** | ✅ | You must provide one of the following to identify the data Snyk should pull for each entity:`snyk.io/target-id`: A single target by name or ID (faster with ID) `snyk.io/targets`: One or more targets by name or ID, comma-separated `snyk.io/project-ids`: One or more project IDs, comma-separated (see slug in project URL or ID in settings) | | **Exclude Project IDs** | ❌ | Optionally exclude specific projects using `snyk.io/exclude-project-ids` (comma-separated) | ### Snyk references (Entity YAML) Add the following references to your entity YAML to connect Backstage entities to the correct Snyk data: | Reference | Description | | ----------------------------- | ---------------------------------------------------------------------------------------------- | | `snyk.io/org-id` | The ID of the Snyk organization (found in _Org Settings_). | | `snyk.io/org-ids` | Comma-separated list of org IDs. If used, this overrides org-id. | | `snyk.io/target-id` | A single target by name or ID. Using the ID avoids an API call. | | `snyk.io/targets` | Comma-separated list of targets by name or ID. | | `snyk.io/project-ids` | Comma-separated list of project IDs (from project slug in the URL or from _Project Settings_). | | `snyk.io/exclude-project-ids` | Comma-separated list of project IDs to be excluded from display. | :::tip Here are some tips for finding the Snyk information detailed in the table above: - **Org ID** - Go to **Snyk Dashboard > Organization Settings**, and copy the `orgId` listed. - **Target IDs** - Use Snyk’s API endpoint: `GET /org/{org_id}/targets` This returns a list of available target IDs linked to your organization. - **Project IDs** - Navigate to a specific project in the Snyk dashboard. The ID is visible in the project URL (slug) or in _Project Settings_. ::: ## Configuring the Snyk Plugin in Venue.sh 1. In the Venue.sh app, click **Plugins** in the left-side navigation. 2. Find Snyk, then click **Enable Plugin**. 3. Enter the value for **API URL**. Use the correct API base URL based on where your Snyk account is hosted: | Region | API URL | | -------------- | ---------------------- | | **SNYK-US-01** | https://api.snyk.io | | **SNYK-US-02** | https://api.us.snyk.io | | **SNYK-EU-01** | https://api.eu.snyk.io | | **SNYK-AU-01** | https://api.au.snyk.io | :::tip You can find your region in your organization’s Snyk dashboard or by contacting your Snyk account manager. ::: 4. Enter the value for **Auth Token**. This value is generated from your Snyk account (**Account Settings > API Token**). :::note The auth token must be re-entered if plugin settings are changed. ::: 5. Click **Validate & Enable**. --- ## SonarQube Plugin This page helps you generate an access token for SonarQube and configure the necessary settings to integrate SonarQube with your developer platform. ## Generating a Personal Access Token If available, use a service account for this task. 1. Open your SonarQube instance, and log in to your account. 2. Click your profile picture or avatar at the top right corner, then select **My Account** from the dropdown menu. 3. Click the **Security** tab. 4. In the _Generate Tokens_ section, enter a name for your token, such as "Venue.sh Token." 5. From the **Type** dropdown, select **Global Analysis Token**. 6. Click **Generate**. A new token appears. 7. Copy the token to your clipboard. :::tip Make sure you save the token in a secure place. You won't be able to see it again! ::: ## Configuring the SonarQube Plugin in Venue.sh 1. In the Venue.sh app, click **Plugins** in the left-side navigation. 2. Find SonarQube, then click **Enable Plugin**. 3. Enter the values for the following three fields: - **API BaseURL**: The URL for the SonQube API. - Format: `https:///api` - Example: `https://your.sonarqube.instance.com/api` - **Token**: The token you generated in the previous section. - **Base URL**: The base URL for your SonarQube instance. - Format: `https://` - Example: `https://your.sonarqube.instance.com` 4. Click **Enable**. ## Component Setup To connect your SonarQube project, add the following annotion to your component catalog-info.yaml file: ```yaml metadata: annotations: sonarqube.org/project-key: [YOUR_PROJECT_KEY] ``` --- ## Terraform Plugin Here we'll help you generate an access token for Terraform Cloud and configure the necessary settings to integrate Terraform Cloud with your developer platform. ## Generating an Access Token for Terraform Cloud Terraform supports multiple types of API tokens with varying levels of access: - **User API tokens** - Tokens that belong to a specific user that reflect the same permission level as your user account. User tokens are the only token type that can be granted access to multiple organizations. - **Team API tokens** - Tokens that belong to a specific team which are used by services, for example a CI/CD pipeline, to perform plans and applies on a workspace. - **Organization API tokens** - Tokens that belong to an organization that are used to manage teams, team membership, and workspaces. Organization tokens do not have permission to perform plans and applies in workspaces. - **Audit API tokens** - Tokens that provide read-only access for the audit trails API. You can configure the Terraform plugin in Venue.sh using any token type. 1. Navigate to the [API tokens page](https://app.terraform.io/app/settings/tokens) in your Terraform Cloud account. :::tip Consider creating a dedicated automation/bot account at the user level for API usage. ::: 2. Once logged in to your account, create an API token of your choice. 3. In the token-creation modal, enter a token description, like "Venue.sh," for easy identification later. :::note Terraform Cloud displays the API token only once! Copy and save it in a safe location, as you will not be able to view it again. ::: ## Configuring the Terraform Plugin in Venue.sh 1. In the Venue.sh app, click **Plugins** in the left-side navigation. 2. Find Terraform, then click **Enable Plugin**. 3. Paste the Terraform token you created in the previous section into the **Terraform Token** field. 4. Click **Enable**. ## Component Setup Within your component catalog-info.yaml file, add the following annotations to connect up your Terraform Cloud: ```yaml metadata: annotations: terraform/organization: YOUR_ORGANIZATION terraform/workspaces: YOUR_WORKSPACE ``` You can add multiple workspaces by adding more workspaces to the `terraform/workspaces` annotation: ```yaml metadata: annotations: terraform/organization: YOUR_ORGANIZATION terraform/workspaces: YOUR_WORKSPACE,YOUR_WORKSPACE_2,YOUR_WORKSPACE_3 ``` --- ## RBAC (Role-Based Action Control) RBAC in Venue.sh is a powerful yet easy-to-use feature that helps you manage access to resources and actions within the platform. It enables fine-grained control by assigning users predefined roles when they are added to teams. ![Role selection](./assets/rbac-role-selection.png) :::info Custom RBAC roles or permissions are not supported at this time. ::: ## Assigning Roles and Permissions When an admin or editor adds a user to a team, they must assign the user one of the four predefined roles described below: - **Admin** - The admin role has the highest level of access. Admins can create, read, update, and delete all items in a Venue. Admin is the only role with permission to delete an organization. Admins, along with editors, can also manage users within their organization. - **Editor** - Editors can create, read, update, and delete nearly all items in a Venue. Like admins, they can manage user roles and team settings, including inviting other users to the team. - **Contributor** - Contributors have the same broad read access as viewers. However, unlike viewers, they can import and manage their own entities and adjust team settings. Contributors do not have permission to manage user settings. - **Viewer** - The Viewer role provides read-only access across the organization. Viewers cannot create, update, or delete any items. :::info - **Role-based dashboard view** - Your Venue dashboard and available actions will vary depending on your assigned role. For example, since users with the viewer role have no import permissions, import-related content does not appear on the viewer's dashboard. - Onboarding steps for new users also vary based on assigned role. ::: ## Roles and Permissions Breakdown by Feature | Feature | Admin | Editor | Contributor | Reader | | --------------------------------- | ---------------------------- | ---------------------------- | --------------------------------- | --------------------------------- | | **Home (workspace)** | Read | Read | Read | Read | | **Workspace - Manage** | Create, Read, Update, Delete | Create, Read, Update, Delete | N/A | N/A | | **Onboarding** | Create, Read, Update | Create, Read, Update | N/A | N/A | | **Assistant** | Read | Read | Read | Read | | **Assistant (Settings)** | Create, Read, Update, Delete | N/A | N/A | N/A | | **Activity log** | Create, Read, Update | N/A | N/A | N/A | | **Catalog entities** | Create, Read, Update, Delete | Create, Read, Update, Delete | Read | Read | | **Git connections** | Create, Read, Update, Delete | Create, Read, Update, Delete | Read | Read | | **Plugins** | Create, Read, Update, Delete | Create, Read, Update, Delete | Read | Read | | **Imports** | Create, Read | Create, Read | Create, Read | N/A | | **Teams** | Create, Read, Update, Delete | Create, Read, Update, Delete | Create, Read, Update, Delete | Read | | **Users** | Create, Read, Update, Delete | Create, Read, Update, Delete | Read | Read | | **Account settings (profile)** | Create, Read, Update, Delete | Create, Read, Update, Delete | Read, Update (personal info only) | Read, Update (personal info only) | | **Organization settings** | Create, Read, Update, Delete | N/A | N/A | N/A | | **Scorecards** | Create, Read, Update, Delete | Create, Read, Update, Delete | Read | Read | | **Development Insights** | Create, Read, Update, Delete | Read | Read | Read | | **Development Insights (Config)** | Create, Read, Update, Delete | N/A | N/A | N/A | | **Jira Connections** | Create, Read, Update, Delete | N/A | N/A | N/A | | **Agents** | Create, Read, Update, Delete | Create, Read, Update, Delete | Read | Read | | **MCP Servers** | Create, Read, Update, Delete | Create, Read, Update, Delete | Read | Read | | **Skills** | Read | Read | Read | Read | ## Development Insights Access Notes - The Development Insights sidebar visibility uses an enabled-state endpoint that requires **Development Insights read** permission, so contributors and readers can see the feature when it is enabled for the organization. - The main Development Insights page requires **read** permission. - The Jira Connections page requires **create, read, update, and delete** permissions, so only admins can access it. --- ## Expressions Scorecards uses an intuitive, JSON path-like syntax to define both entity selection and validation rules. This powerful expression system allows you to create precise, targeted validations for your Backstage entities. ## Understanding Expressions Expressions in Scorecards serve two main purposes: - Selecting which entities a rule applies to, and - Defining validation criteria for those entities. :::info All expressions use a consistent syntax based on JSON path, making them easy to learn and maintain. ::: ## Selector Expressions Selectors determine the scope of your rules using a simple, clear syntax: ``` $kind is ``` For example: - `$kind is Component` targets all component entities - `$kind is API` targets all API entities ## Available Operators Scorecards provides a rich set of operators for building expressions: ### Comparison operators - `==` - Equality comparison - `!=` - Inequality comparison - `>` - Greater than - `<` - Less than - `>=` - Greater than or equal - `<=` - Less than or equal - `is` - Case-insensitive string equality - `~` - Regular expression match ### Logical operators - `and` - Logical AND - `and`, `AND` and `&&` are equivalent - `or` - Logical OR - `or`, `OR` and `||` are equivalent - `not` - Logical NOT - `not` and `NOT` are equivalent ### Access operators - `.` - Property access (e.g., `$metadata.name`) - `@` - Array index access ### Arithmetic operators - `+` - Addition - `-` - Subtraction - `*` - Multiplication - `/` - Division :::info Operators follow a precedence order (highest to lowest): 1. Access (`.`, `@`) 2. Arithmetic (`*`, `/`, `+`, `-`) 3. Comparison (`>`, `<`, `>=`, `<=`) 4. Equality (`==`, `!=`, `is`, `~`) 5. Logical (`and`, `or`) ::: ## Field References Scorecards provides several special fields for accessing entity data: - **$entity** - Access the entire entity object. - **$kind** - Access the entity kind. ``` $kind is Component ``` - **$metadata** - Access core entity information. ``` $metadata.name # Entity name $metadata.owner # Entity owner ``` - **$namespace** - Access the entity namespace. ``` $namespace == "default" ``` - **$spec** - Reference entity specifications. ``` $spec.type # Entity type $spec.lifecycle # Lifecycle stage $spec.definition # API definition ``` - **$annotations** - Access integration metadata. ``` $annotations."gitlab.com/instance" # GitLab instance $annotations."gitlab.com/project-slug" # GitLab project $annotations."jira/project-key" # Jira project ``` ## Rule Examples Here are examples from the pre-configured [golden rules](/docs/scorecards/#golden-rules): - **API Validation** ``` $metadata.name and $spec.type and $spec.lifecycle and $spec.owner and $spec.definition ``` - **Component Validation** ``` $metadata.name and $spec.type and $spec.lifecycle and $spec.owner ``` - **GitLab Integration** ``` $annotations."gitlab.com/instance" and $annotations."gitlab.com/project-slug" ``` - **Jira Integration** ``` $annotations."jira/project-key" ``` :::info Rules use the `and` operator to combine multiple criteria. All conditions must be true for validation to pass. ::: ## Best Practices Follow these guidelines for effective rule creation: - **Clear selectors**: Use specific entity types to target the right components. - **Focused validation**: Keep each validation criteria focused on a single aspect. - **Consistent paths**: Use standard annotation paths across related rules. - **Logical grouping**: Group related validations together for better organization. - **Documentation**: Add clear descriptions for complex validation rules. - **Operator precedence**: Be aware of operator precedence and use parentheses when needed. - **Field access**: Use the most specific field accessor for your needs. --- ## Scorecards Scorecards is a powerful validation framework in Venue.sh that ensures your Backstage entities meet defined standards. It uses customizable rules to validate entities in real time, checking for required metadata, specifications, and annotations. Each rule acts as a quality gate, providing clear pass/fail metrics to help you track compliance and identify areas that need attention. Venue.sh comes with four pre-installed golden rules, maintained by the Venue.sh team, to ensure consistent quality standards. ## Benefits Scorecards provide many advantages for your development workflow, including: - **Quality assurance** by ensuring all entities meet required standards, - **Integration validation** by verifying proper tool configurations, - **Compliance monitoring** by tracking validation statuses in real-time, - **Standardization** by maintaining consistency across your catalog, and - **Clear metrics** by easily identifying areas that need attention. ## Golden Rules The following rules are configured out of the box and ready to use in your Venue.sh instance: - **API Rule** - Validates API entities by ensuring they have all required metadata and specifications. This rule checks for essential fields, like **Name**, **Type**, **Lifecycle**, **Owner**, and **Definition**. - **Component Rule** - Ensures component entities have complete metadata and specifications. This rule validates critical fields, including **Name**, **Type**, **Lifecycle**, and **Owner**. - **GitLab Rule** - Validates GitLab integration settings by checking for required annotations. This rule ensures proper GitLab instance and project slug configurations. - **Jira Rule** - Verifies Jira integration settings through annotation validation. This rule checks for proper Jira project key configuration. Here's an example of the golden rules and the feedback they provide: ![Example of the four pre-installed golden rules in Scorecards](../assets/rules-table.png) ## Writing Rules Each Scorecards rule requires the following information: - **Title** - A unique identifier for the rule - **Description** - Clear purpose of the validation - **Owner** - Team responsible for maintenance - **Tags** - Categories for organization - **Category** - Organizational descriptor - **Selector** - Entity type the rule applies to. It uses the expression language to select the entities. - **Criteria** - Required conditions for validation. It uses the expression language to validate the entities. :::tip In the _Rule Parameters_ section, toggle on the **Advanced** option to write your rules manually, opposed to making selections via dropdown lists. Note that if you edit a rule using the advanced method, you cannot switch back to basic. ::: Here's an example of an API rule: ![Scorecards rule creation](../assets/scorecards-rule-creation.png) :::tip Detailed information about rule syntax and writing expressions can be found on the [Expressions](./expressions.md) page. :::