1# GitLab CI/CD Deployment
2
3Automated deployment with GitLab CI/CD using Gordon's push command.
4
5## Prerequisites
6
71. Gordon server running with registry authentication enabled
82. Generated deployment token
93. GitLab CI/CD variables configured
10
11## Quick Setup
12
13### 1. Generate Deployment Token
14
15On your Gordon server:
16
17```bash
18gordon auth token generate \
19  --subject gitlab-ci \
20  --scopes "push,pull,admin:routes:read,admin:config:write" \
21  --expiry 0
22```
23
24### 2. Add CI/CD Variables
25
26In your project: Settings > CI/CD > Variables
27
28| Variable | Value | Protected | Masked |
29|----------|-------|-----------|--------|
30| `GORDON_TOKEN` | The generated token | Yes | Yes |
31| `GORDON_REMOTE` | `https://gordon.example.com` | Yes | No |
32
33### 3. Create Pipeline
34
35Create `.gitlab-ci.yml`:
36
37```yaml
38deploy:
39  stage: deploy
40  image: docker:24
41  services:
42    - docker:24-dind
43  before_script:
44    - apk add --no-cache curl
45    - curl -fsSL https://github.com/bnema/gordon/releases/latest/download/gordon_linux_amd64 -o /usr/local/bin/gordon
46    - chmod +x /usr/local/bin/gordon
47  script:
48    - gordon push --build
49        --remote "$GORDON_REMOTE"
50        --token "$GORDON_TOKEN"
51        --no-confirm
52  only:
53    - tags
54```
55
56Gordon auto-detects the version from `$CI_COMMIT_TAG`.
57
58## Pipeline Examples
59
60### Deploy on Tag Push
61
62```yaml
63stages:
64  - deploy
65
66deploy:
67  stage: deploy
68  image: docker:24
69  services:
70    - docker:24-dind
71  before_script:
72    - apk add --no-cache curl
73    - curl -fsSL https://github.com/bnema/gordon/releases/latest/download/gordon_linux_amd64 -o /usr/local/bin/gordon
74    - chmod +x /usr/local/bin/gordon
75  script:
76    - gordon push --build
77        --remote "$GORDON_REMOTE"
78        --token "$GORDON_TOKEN"
79        --no-confirm
80  rules:
81    - if: $CI_COMMIT_TAG
82```
83
84### Continuous Deployment
85
86Deploy on every push to main:
87
88```yaml
89deploy:
90  stage: deploy
91  image: docker:24
92  services:
93    - docker:24-dind
94  before_script:
95    - apk add --no-cache curl
96    - curl -fsSL https://github.com/bnema/gordon/releases/latest/download/gordon_linux_amd64 -o /usr/local/bin/gordon
97    - chmod +x /usr/local/bin/gordon
98  script:
99    - gordon push --build
100        --remote "$GORDON_REMOTE"
101        --token "$GORDON_TOKEN"
102        --no-confirm
103  rules:
104    - if: $CI_COMMIT_BRANCH == "main"
105```
106
107### Manual Deployment
108
109```yaml
110deploy:
111  stage: deploy
112  image: docker:24
113  services:
114    - docker:24-dind
115  before_script:
116    - apk add --no-cache curl
117    - curl -fsSL https://github.com/bnema/gordon/releases/latest/download/gordon_linux_amd64 -o /usr/local/bin/gordon
118    - chmod +x /usr/local/bin/gordon
119  script:
120    - gordon push --build
121        --remote "$GORDON_REMOTE"
122        --token "$GORDON_TOKEN"
123        --no-confirm
124  when: manual
125```
126
127### With Build Arguments
128
129```yaml
130deploy:
131  stage: deploy
132  image: docker:24
133  services:
134    - docker:24-dind
135  before_script:
136    - apk add --no-cache curl
137    - curl -fsSL https://github.com/bnema/gordon/releases/latest/download/gordon_linux_amd64 -o /usr/local/bin/gordon
138    - chmod +x /usr/local/bin/gordon
139  script:
140    - gordon push --build
141        --remote "$GORDON_REMOTE"
142        --token "$GORDON_TOKEN"
143        --build-arg NODE_ENV=production
144        --build-arg API_URL=https://api.example.com
145        --no-confirm
146  rules:
147    - if: $CI_COMMIT_TAG
148```
149
150## Alternative: Docker-based Pipeline
151
152For environments where installing the Gordon binary is not desired:
153
154```yaml
155deploy:
156  stage: deploy
157  image: docker:24
158  services:
159    - docker:24-dind
160  script:
161    - echo "$GORDON_TOKEN" | docker login "$GORDON_REGISTRY" -u "$GORDON_USERNAME" --password-stdin
162    - docker build -t "$GORDON_REGISTRY/myapp:$CI_COMMIT_TAG" .
163    - docker push "$GORDON_REGISTRY/myapp:$CI_COMMIT_TAG"
164  rules:
165    - if: $CI_COMMIT_TAG
166```
167
168This requires additional CI/CD variables: `GORDON_REGISTRY` and `GORDON_USERNAME`.
169Gordon auto-deploys when it receives the image.
170
171## Version Detection
172
173Gordon automatically detects the version tag from GitLab CI environment variables:
174
175| Variable | Example | Result |
176|----------|---------|--------|
177| `$CI_COMMIT_TAG` | `v1.2.0` | Tag `v1.2.0` |
178| No tag | - | Falls back to `git describe` or `latest` |
179
180## Troubleshooting
181
182### Authentication Failed
183
184```text
185Error: failed to verify token
186```
187
188Verify `GORDON_TOKEN` is correctly set and the token has not been revoked.
189
190### Docker-in-Docker Issues
191
192If using `docker:dind`, ensure the service is properly configured:
193
194```yaml
195services:
196  - docker:24-dind
197variables:
198  DOCKER_TLS_CERTDIR: "/certs"
199```
200
201### Build Context
202
203GitLab CI clones your repository automatically. The build context defaults to the repository root.
204
205## Related
206
207- [GitHub Actions](./github-actions.md)
208- [Generic CI](./generic-ci.md)
209- [Deployment Overview](./index.md)
210- [Authentication](../config/auth.md)
211- [Push Command](../cli/push.md)