1# Generic CI/CD Deployment
2
3Deploy with Gordon from any CI/CD system.
4
5## Requirements
6
7- Docker available on CI runner (for building images)
8- Network access to your Gordon server (HTTPS)
9- Gordon binary (optional but recommended)
10
11## Recommended: gordon push
12
13### 1. Generate Deployment Token
14
15On your Gordon server:
16
17```bash
18gordon auth token generate \
19  --subject ci-deploy \
20  --scopes "push,pull,admin:routes:read,admin:config:write" \
21  --expiry 0
22```
23
24### 2. Configure CI Secrets
25
26Add these secrets to your CI system:
27
28| Secret | Value |
29|--------|-------|
30| `GORDON_TOKEN` | The generated token |
31| `GORDON_REMOTE` | `https://gordon.example.com` |
32
33### 3. Pipeline Steps
34
35```bash
36# 1. Install Gordon binary
37curl -fsSL https://github.com/bnema/gordon/releases/latest/download/gordon_linux_amd64 \
38  -o /usr/local/bin/gordon
39chmod +x /usr/local/bin/gordon
40
41# 2. Build, push, and deploy
42export GORDON_TOKEN="$GORDON_TOKEN"
43gordon push --build \
44  --remote "$GORDON_REMOTE" \
45  --no-confirm
46```
47
48Gordon auto-detects the version from CI environment variables:
49
50| CI System | Variable | Example |
51|-----------|----------|---------|
52| GitHub Actions | `$GITHUB_REF` | `refs/tags/v1.2.0` |
53| GitLab CI | `$CI_COMMIT_TAG` | `v1.2.0` |
54| Azure DevOps | `$BUILD_SOURCEBRANCH` | `refs/tags/v1.2.0` |
55| Other | `--tag` flag | `gordon push --tag v1.2.0` |
56
57## Alternative: docker push
58
59If installing the Gordon binary is not possible:
60
61```bash
62# 1. Login to Gordon registry
63echo "$GORDON_TOKEN" | docker login gordon.example.com \
64  -u ci-deploy --password-stdin
65
66# 2. Build and push
67docker build -t gordon.example.com/myapp:v1.0.0 .
68docker push gordon.example.com/myapp:v1.0.0
69```
70
71This requires the token subject (`ci-deploy`) as the username.
72Gordon auto-deploys when it receives the image.
73
74## CI System Examples
75
76### Jenkins
77
78```groovy
79pipeline {
80    agent any
81    environment {
82        GORDON_TOKEN = credentials('gordon-token')
83        GORDON_REMOTE = 'https://gordon.example.com'
84    }
85    stages {
86        stage('Deploy') {
87            steps {
88                sh '''
89                    curl -fsSL https://github.com/bnema/gordon/releases/latest/download/gordon_linux_amd64 \
90                      -o /usr/local/bin/gordon
91                    chmod +x /usr/local/bin/gordon
92                    gordon push --build --remote "$GORDON_REMOTE" --no-confirm
93                '''
94            }
95        }
96    }
97}
98```
99
100### CircleCI
101
102```yaml
103version: 2.1
104
105jobs:
106  deploy:
107    docker:
108      - image: docker:24
109    steps:
110      - checkout
111      - setup_remote_docker
112      - run:
113          name: Install Gordon
114          command: |
115            apk add --no-cache curl
116            curl -fsSL https://github.com/bnema/gordon/releases/latest/download/gordon_linux_amd64 \
117              -o /usr/local/bin/gordon
118            chmod +x /usr/local/bin/gordon
119      - run:
120          name: Deploy
121          command: |
122            gordon push --build \
123              --remote "$GORDON_REMOTE" \
124              --no-confirm
125
126workflows:
127  deploy:
128    jobs:
129      - deploy:
130          filters:
131            tags:
132              only: /^v.*/
133            branches:
134              ignore: /.*/
135```
136
137### Drone
138
139```yaml
140kind: pipeline
141type: docker
142name: deploy
143
144steps:
145  - name: deploy
146    image: docker:24
147    environment:
148      GORDON_TOKEN:
149        from_secret: gordon_token
150      GORDON_REMOTE:
151        from_secret: gordon_remote
152    commands:
153      - apk add --no-cache curl
154      - curl -fsSL https://github.com/bnema/gordon/releases/latest/download/gordon_linux_amd64 -o /usr/local/bin/gordon
155      - chmod +x /usr/local/bin/gordon
156      - gordon push --build --remote "$GORDON_REMOTE" --no-confirm
157
158trigger:
159  event:
160    - tag
161```
162
163## Token Scopes Reference
164
165| Workflow | Required Scopes |
166|----------|----------------|
167| Build + push + deploy | `push,pull,admin:routes:read,admin:config:write` |
168| Push only (no deploy) | `push,pull,admin:routes:read` |
169| docker push (auto-deploy) | `push,pull` |
170
171## Troubleshooting
172
173### "failed to verify token"
174
175The token is invalid or has been revoked. Generate a new one.
176
177### "no route configured for image"
178
179The route must exist before pushing. Create it with:
180
181```bash
182gordon routes add myapp.example.com myapp
183# or for first deploy:
184gordon bootstrap myapp.example.com myapp
185```
186
187### Version shows "latest"
188
189Gordon could not detect a version tag. Either:
190- Tag your git repo: `git tag v1.0.0 && git push --tags`
191- Pass explicitly: `gordon push --tag v1.0.0`
192
193### Large images time out
194
195Gordon uploads in 50MB chunks. For very large images (> 1GB), the push may take several minutes. Ensure your CI runner timeout is sufficient.
196
197## Related
198
199- [GitHub Actions](./github-actions.md)
200- [GitLab CI](./gitlab-ci.md)
201- [Deployment Overview](./index.md)
202- [Authentication](../config/auth.md)
203- [Push Command](../cli/push.md)