Skip to main content

Application Repositories

This document outlines the convention for application repositories scaffolded via Backstage Golden Paths. While the {domain}-gitops and platform-gitops repositories govern the deployment layer, the application repository gives product teams autonomy over their specific workload configuration.

Golden Path Bootstrapping​

When a new application is scaffolded via Backstage (e.g., using the create-service template), it delivers a fully configured repository containing:

  1. Base Source Code: A boilerplate application structure for the chosen framework (e.g., Node.js, .NET, Python).
  2. Dockerfile: An optimized, secure, non-root container definition tailored to the language.
  3. CI Pipeline: A pre-configured pipeline (e.g., .github/workflows/ci.yaml).
  4. .k8s/ folder: A configuration directory empowering the application team to manage workload-specific resources.

The .k8s Folder and Multiple Sources​

Our platform utilizes ArgoCD's Multiple Sources pattern to merge definitions from both the domain GitOps repository and the application repository:

  • Base Manifests ({domain}-gitops/k8s/): Contains the foundational Kubernetes configuration (Deployments, Services, standard NetworkPolicies) and values files for the service.
  • Application Overrides (app-repo/.k8s/): Contains configuration files (such as a values.yaml or kustomize patch) managed directly by the application team.

This structure allows developers to override critical deployment parameters natively in their application repository without needing PRs on the GitOps repository. Commonly overridden values include:

  • Image version/tag
  • Number of replicas (or HPA min/max thresholds)
  • Memory and CPU requests/limits
  • Application-specific environment variables

Continuous Integration (CI) Flow​

The Golden Path pipeline is designed to provide a seamless transition from code commit to deployment readiness. The CI pipeline executes the following stages:

  1. Test & Lint: Validates the base source code.
  2. Build: Compiles the code and builds the container image using the provided Dockerfile.
  3. Publish: Uploads the resulting container image to the central container registry.
  4. Tag Update: The pipeline automatically updates the image tag inside the .k8s/ folder of the application repository (e.g., updating image.tag in .k8s/values.yaml) and commits this change back to the repository.

Because ArgoCD is configured to watch the application repository as a secondary source, the new image tag commit immediately triggers a deployment sync, pushing the new version to the target environment.