How to Deploy to Kubernetes With the GitLab Agent in GitLab CI/CD

With the GitLab agent installed, a job selects the agent context by name and runs kubectl against the cluster with no stored kubeconfig.

Install the agent and grant the project access, then in CI run kubectl config use-context <path>:<agent> and deploy; the agent proxies the connection.

Steps

• Register the agent and add a config.yaml granting ci_access.
• In the job, run kubectl config use-context <project-path>:<agent-name>.
• Run your kubectl apply or kubectl set image.
• Wait on the rollout to confirm health.

.gitlab-ci.yml

deploy:
  stage: deploy
  image: bitnami/kubectl:1.30
  script:
    - kubectl config get-contexts
    - kubectl config use-context my-group/my-project:prod-agent
    - kubectl apply -f k8s/ -n production
    - kubectl rollout status deployment/myapp -n production --timeout=120s
  environment:
    name: production

Gotchas

• The agent config.yaml must list this project under ci_access, or the context will not appear.
• The context name is <agent-config-project-path>:<agent-name>; a typo gives "context not found".

Related guides