Git on Satellite

git on satellite runs the git integration inside your kubernetes environment through resolve satellite this guide covers git on satellite for kubernetes deployments for aws ecs fargate deployments, see satellite on ecs docid 8i ecgujrxynd72r3aiyk repositories are cloned and managed in your environment code stays in your infrastructure, except for investigation snippets that are sent when needed for analysis overview git on satellite lets resolve ai clone and sync multiple git repositories search repository files and directories read file contents and git history analyze commits, diffs, and blame data propose code changes and open prs when write tooling is enabled when to use it use git on satellite when repositories are private to your network you need in cluster data residency and control you need custom networking and cluster level security controls if you want the fastest setup without running infrastructure, use git on cloud docid\ jnylm3jccqrvieuavzdqs prerequisites resolve satellite deployed in your kubernetes cluster repository hosts reachable from satellite pods kubernetes secret management available helm available for satellite updates available tools the git integration provides git network operations git clone , git fetch local read only git operations history, diffs, file inspection file system/text processing tools used during code analysis write/remediation behavior when enabled code remediation behavior write/remediation tools are controlled by both satellite version support and connection config satellite version remediation tool support v1 0 15+ supported < v1 0 15 not supported write/remediation availability is then gated by connection disablewrites disablewrites true => read only mode disablewrites false => write/remediation tools allowed if omitted defaults to false when any auth config is type "github" or type "ghe" defaults to true for token only auth resolve ai does not automatically push changes without user action pr creation is an explicit user invoked workflow authentication options option 1 github auth (recommended for github) add a git integration with github auth config resolve values yaml integrations gitgithub type git create true connection authconfigs githubapp type "github" gitvolume type persistentvolumeclaim deploy/update satellite helm upgrade install resolve satellite \\ oci //registry 1 docker io/resolveaihq/satellite chart \\ \ values resolve values yaml in resolve ui, open your git integration and click install github app complete github authorization and choose repositories verify health check and repository listing for a github specific walkthrough, see app for github docid\ jr5wemheelnozhvsz81ne option 2 bring your own github app (ghe) use this option when you operate your own custom github app it works against any github variant, github com, github enterprise cloud, or github enterprise server (on prem), including air gapped ghe server reachable only from inside your network the end to end walkthrough, creating the github app, recommended permissions, generating the private key, locating app id / installation id / api base url, and the satellite yaml + secret shape, lives on app for github → bring your own github app docid\ jr5wemheelnozhvsz81ne (open the satellite tab under step 7 docid\ jr5wemheelnozhvsz81ne ) the minimal satellite values are resolve values yaml integrations gitghe type git create true secretname git credentials connection authconfigs mygheapp # must match the key in the gheauthcredentials secret type "ghe" ghe baseurl "https //ghe your company com/api/v3" appid "12345" installationid "67890" gitvolume type persistentvolumeclaim pair with a kubernetes secret containing gheauthcredentials \<authconfigname> privatekey for a self signed ghe server, also add trustedcertificateoverrides \<authconfigname> , see custom ssl certificates docid\ xpgmd3gralx1wkgfybh8a combining ghe with github and token auth a single git integration can mix github , ghe , and token auth configs use this to cover, for example, github com repos via the resolve app plus an on prem ghe instance plus a gitlab org over a pat, all in one integration resolve values yaml integrations gitmulti type git create true secretname git credentials connection authconfigs \# resolve managed github app on github com githubcloud type "github" \# custom github app on a ghe server instance mygheapp type "ghe" ghe baseurl "https //ghe your company com/api/v3" appid "12345" installationid "67890" \# gitlab via pat gitlabtoken type "token" tokenauthremoteurls \ "https //gitlab com/your group/repo a git" gitvolume type persistentvolumeclaim the matching secret holds credentials keyed by auth config name git credentials yaml apiversion v1 kind secret type opaque metadata name git credentials stringdata gheauthcredentials | mygheapp privatekey | \ begin rsa private key \ end rsa private key tokenauthcredentials | gitlabtoken username \<gitlab username> token \<gitlab token> the github auth type does not need a secret entry, its tokens are managed by github app installation metadata refreshed by resolve option 3 token auth token auth uses matching keys between connection authconfigs and credentials in your kubernetes secret step 1 create access tokens create provider tokens first see creating personal access tokens docid\ xpgmd3gralx1wkgfybh8a step 2 create kubernetes secret git credentials yaml apiversion v1 kind secret type opaque metadata name git credentials stringdata tokenauthcredentials | githubtoken # key name used in step 3 authconfigs username \<github username> token \<github token> \# optional per auth custom certificate overrides trustedcertificateoverrides | githubtoken | # must use the same key name as tokenauthcredentials/authconfigs \ begin certificate \ end certificate git credentials yaml apiversion v1 kind secret type opaque metadata name git credentials stringdata tokenauthcredentials | githuborgonetoken # github org one credentials username \<github username> token \<github token org one> githuborgtwotoken # github org two credentials username \<github username> token \<github token org two> gitlabtoken # gitlab credentials username \<gitlab username> token \<gitlab token> \# optional per auth custom certificate overrides trustedcertificateoverrides | gitlabtoken | # needed only for custom/self signed gitlab certs \ begin certificate \ end certificate apply secret kubectl apply f git credentials yaml step 3 configure integration resolve values yaml integrations gittoken type git create true secretname git credentials connection authconfigs githubtoken # must match key in secret type "token" tokenauthremoteurls \ "https //github com/your org/repo 1 git" \ "https //github com/your org/repo 2 git" \# recommended for production gitvolume type persistentvolumeclaim resolve values yaml integrations gittoken type git create true secretname git credentials connection authconfigs githuborgonetoken # must match key in secret (github org one) type "token" tokenauthremoteurls \ "https //github com/org one/repo 1 git" \ "https //github com/org one/repo 2 git" githuborgtwotoken # must match key in secret (github org two) type "token" tokenauthremoteurls \ "https //github com/org two/repo 1 git" gitlabtoken # must match key in secret (gitlab) type "token" tokenauthremoteurls \ "https //gitlab com/group one/repo 1 git" \ "https //gitlab com/group two/repo 2 git" \# recommended for production gitvolume type persistentvolumeclaim step 4 deploy helm upgrade install resolve satellite \\ oci //registry 1 docker io/resolveaihq/satellite chart \\ \ values resolve values yaml key matching rule connection authconfigs \<name> must match the credential key exactly tokenauthcredentials \<name> for type token gheauthcredentials \<name> for type ghe if used, trustedcertificateoverrides \<name> must use the same key how token auth mapping works authconfigs \<name> tokenauthremoteurls defines which repositories use that auth config tokenauthcredentials \<name> provides the username/token for those repositories optional trustedcertificateoverrides \<name> adds a per auth custom cert for tls verification how ghe auth mapping works authconfigs \<name> type "ghe" declares a byo github app auth config authconfigs \<name> ghe {baseurl, appid, installationid} points the satellite at the right github instance and app installation repositories are discovered automatically from the installation, no tokenauthremoteurls needed gheauthcredentials \<name> privatekey provides the pem private key for the app optional trustedcertificateoverrides \<name> adds a per auth custom cert for self signed ghe server storage configuration satellite clones repositories into gitvolume default ( emptydir ) ephemeral default size 10gi full re clone after pod restart gitvolume type emptydir emptydir sizelimit 10gi recommended for production (pvc) persistent across restarts better for large repositories and faster restart recovery gitvolume type persistentvolumeclaim persistentvolumeclaim spec accessmodes \ readwriteonce resources requests storage 100gi advanced configuration custom ssl certificates for self hosted git with private ca or self signed certificates, set trustedcertificateoverrides using the auth config key git credentials yaml apiversion v1 kind secret type opaque metadata name git credentials stringdata tokenauthcredentials | selfhosted username \<username> token \<token> trustedcertificateoverrides | selfhosted | \ begin certificate \ end certificate gitsslnoverify (use carefully) connection gitsslnoverify true gitvolume type persistentvolumeclaim disabling ssl verification weakens transport security prefer trustedcertificateoverrides when possible disablewrites connection disablewrites true gitvolume type persistentvolumeclaim use this for strict read only mode disabledsubcommands connection disabledsubcommands \["config", "remote"] gitvolume type persistentvolumeclaim use this to block specific git \<subcommand> operations schema reference the connection schema supports inline credentials and certificate overrides for satellite deployments, we recommend storing tokenauthcredentials , gheauthcredentials , and trustedcertificateoverrides in a kubernetes secret ( secretname ) instead of inline resolve values yaml connection authconfigs \<authname> type "token" | "github" | "ghe" tokenauthremoteurls \[" "] # required for type token ghe # required for type ghe baseurl "https //ghe example com/api/v3" appid "12345" installationid "67890" tokenauthcredentials # schema supported inline form \<authname> username " " token " " gheauthcredentials # schema supported inline form \<authname> privatekey | \ begin rsa private key \ end rsa private key trustedcertificateoverrides # schema supported inline form \<authname> | \ begin certificate \ end certificate gitsslnoverify false disablewrites true disabledsubcommands \[] gitvolume type persistentvolumeclaim repository url formats use https urls only supported examples https //github com/org name/repo name git https //gitlab com/org name/repo name git https //bitbucket org/org name/repo name git https //github company com/org name/repo name git creating personal access tokens github github supports fine grained and classic pats fine grained token (recommended) go to settings > developer settings > personal access tokens > fine grained tokens click generate new token set token name and expiration choose resource owner and repository access set repository permissions contents read only (or write if you need write/remediation) metadata read only (mandatory) for pr data and github actions / check status reads, also grant pull requests read only , actions read only , checks read only generate and copy token classic token go to settings > developer settings > personal access tokens > tokens (classic) generate token and set expiration scopes private repositories repo public only workflows public repo authorize sso for your org if required copy token classic pats with repo scope are broad prefer fine grained pats when possible gitlab go to preferences > access tokens create token with expiration add scope read repository (or additional write scopes if required) copy token how it works (satellite path) integrations gateway resolves auth configs and prepares tool commands github auth repository lists come from github installation metadata refresh (works for both github and ghe auth, ghe calls the configured baseurl ) token auth credentials/certs are resolved from the secret backed connection data ghe auth credentials (private key) are resolved from gheauthcredentials and used to mint short lived installation tokens against the configured baseurl refresh uses cloneorfetch with configured concurrency limits read commands can execute against specific refs using temporary worktrees command validation enforces path safety and blocked subcommands tooling notes read capabilities search, file read/list, git history/diff, metadata operations github specific read capabilities (reading pr data; reading github actions workflow runs / definitions and pr check status) available with github or ghe auth, or with token auth pointed at github repos when the token grants the equivalent scopes (actions, checks, pull requests, contents, metadata) write/remediation capabilities available when enabled (see disablewrites ) troubleshooting health check failures verify token/username values in secret (token auth) verify gheauthcredentials \<name> privatekey is valid pem (ghe auth) verify authconfigs keys match secret keys verify satellite can reach repository host (and the configured ghe baseurl for ghe auth) verify certificate content is valid pem for custom cert overrides clone failures authentication failed token invalid/expired or missing required repo permissions network timeout/refusal repository host unreachable from satellite network disk pressure insufficient storage for clone/fetch operations invalid url format url must be https and reachable refresh issues check whether credentials changed recently validate repository host connectivity from cluster ensure there is enough storage headroom for fetch/submodule updates unexpected read only behavior check if disablewrites is explicitly true if omitted, token only auth defaults to read only check satellite version support ( v1 0 15+ required for remediation tools) frequently asked questions how often are repositories synced? repositories are refreshed during scheduled scrape/health workflows in practice this is typically every few minutes depending on your org scrape cadence can resolve ai modify my repositories? by default, write availability depends on auth type and disablewrites any github or ghe auth config + disablewrites omitted => writes enabled by default token only auth + disablewrites omitted => read only by default in both cases, pr creation/remediation still occurs through explicit user invoked workflows how much disk space do i need? plan for total repository size plus git metadata and growth a practical baseline is total repo size x 1 5 to 2 0 should i use pvc or emptydir ? use pvc for production use emptydir only when re cloning after restarts is acceptable can i use ssh urls? no use https repository urls what is the difference between github , ghe , and token auth? github auth resolve managed github app on github com tokens and metadata are managed by resolve works only against github com ghe auth bring your own github app on any github instance (github com, github enterprise cloud, or github enterprise server) you provide app id, installation id, private key, and the api base url use this when you cannot install the resolve github app, or you need air gapped ghe server access token auth direct username/pat for any https git host (gitlab, bitbucket, azure devops, github via pat, self hosted git) all three can be read only or write enabled depending on disablewrites and satellite version reading pr data and querying github actions / pr check status works with github or ghe auth, and with token auth pointed at github repos as long as the token carries the equivalent scopes can i mix github , ghe , and token auth in one integration? yes multiple auth configs can coexist under authconfigs for example, you can combine github auth for github com repos, ghe auth for an on prem ghe instance, and one or more token auth configs for gitlab/bitbucket/etc, all in a single git integration how do i add more repositories? github / ghe auth grant additional repos during app installation or update on the github instance they appear automatically on the next refresh token auth add repository urls under the correct tokenauthremoteurls auth config and redeploy how do i rotate credentials? generate new token(s) update the kubernetes secret reapply secret restart satellite pods if required by your secret propagation model kubectl apply f git credentials yaml kubectl rollout restart statefulset/resolve satellite what happens if a token expires? health checks and refresh operations for that auth config will fail until token credentials are updated can i configure different permissions for different repositories? yes use multiple auth configs, each with different credentials and repository url sets this lets you isolate permissions by team, provider, or repository group are there limits on concurrent operations and repository size? there are no hardcoded per repo size limits in docs level config practical limits come from satellite cpu, memory, network throughput, and storage capacity adjust resources and storage based on repo count/size and refresh concurrency can token auth use write/remediation tools? yes, when disablewrites false and satellite version support is available ( v1 0 15+ )