Skip to content

Commit f709656

Browse files
StashBankStashBank
authored
feat: server token (#158)
1 parent 39a57a8 commit f709656

File tree

9 files changed

+241
-8
lines changed

9 files changed

+241
-8
lines changed

docs/features/ci-cd.mdx renamed to docs/features/ci-cd-personal-token.mdx

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,11 @@
11
---
2-
title: CI/CD
2+
title: CI/CD - Personal token
33
description: Integrate Zephyr Cloud with your continuous integration and deployment pipelines
44
---
55

66
import { Steps } from '@rspress/core/theme';
77

8-
# CI/CD Integration
8+
# CI/CD Integration using Personal token
99

1010
Integrate Zephyr Cloud into your continuous integration and deployment pipelines to automate your deployment workflow. This guide covers setup for GitHub Actions and GitLab CI/CD.
1111

‎docs/features/ci-cd-server-token.mdx‎

Lines changed: 227 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,227 @@
1+
---
2+
title: CI/CD - Server token
3+
description: The Server Auth Token allows you to authenticate Zephyr plugins at the organization level without needing individual user credentials for every operation. It identifies the user performing actions via their email and enables secure access to Zephyr on behalf of your organization.
4+
---
5+
6+
import { Steps } from '@rspress/core/theme';
7+
8+
# CI/CD Integration using Server token
9+
10+
The Server Auth Token allows you to authenticate Zephyr plugins at the organization level without needing individual user credentials for every operation. It identifies the user performing actions via their email and enables secure access to Zephyr on behalf of your organization.
11+
12+
## Overview
13+
14+
- [Generate API Token](#generate-an-server-api-token)
15+
- [GitHub Actions Setup](#github-actions)
16+
- [GitLab CI/CD Setup](#gitlab-cicd)
17+
- [Troubleshooting](#troubleshooting)
18+
19+
## Generate an Server API Token
20+
21+
To use Zephyr Cloud in CI/CD pipelines, you'll need an API token for authentication:
22+
23+
<Steps>
24+
### Organization Settings
25+
26+
Go to your Organization Settings in Zephyr.
27+
28+
![org settings screen](../public/org-settings-screen.webp)
29+
30+
### Server Tokens section
31+
32+
Navigate to the Server Tokens section.
33+
34+
![server token section screen](../public/server-token-section-screen.webp)
35+
36+
### Click Generate Token Button
37+
38+
Fill out the required information about the token you're about to generate
39+
40+
![server token screen](../public/server-token-screen.webp)
41+
42+
### Click Generate
43+
44+
Copy the token for usage where you need to use it
45+
46+
![server token created screen](../public/server-token-created-screen.webp)
47+
48+
</Steps>
49+
50+
## GitHub Actions
51+
52+
Zephyr requires an authenticated user to publish updates. Configure your GitHub Actions pipeline to build and deploy with Zephyr by adding a token to your repository secrets.
53+
54+
### Adding the GitHub Secret
55+
56+
1. Create a token on your organization settings page
57+
2. Add it as a repository secret in GitHub
58+
3. The secret must be assigned to the `ZE_SERVER_TOKEN` environment variable
59+
4. Set user email
60+
61+
```yml title="pull_request.yml"
62+
env:
63+
ZE_SERVER_TOKEN: ${{ secrets.ZEPHYR_AUTH_TOKEN }}
64+
ZE_USER_EMAIL: <User Email>
65+
```
66+
67+
### Authentication Behavior
68+
69+
When the Zephyr plugin detects the `ZE_SERVER_TOKEN` environment variable, it will automatically authenticate with the Zephyr API, bypassing the usual login step.
70+
The Zephyr needs a user email to identify who is performing builds. You can provide it in one of two ways:
71+
72+
- Automatically from Git config
73+
- Manually via environment variable `ZE_USER_EMAIL`
74+
75+
You'll see this confirmation in the console:
76+
77+
```shell
78+
ZEPHYR Token found in environment. Using secret token for authentication.
79+
```
80+
81+
## GitLab CI/CD
82+
83+
Configure your GitLab Runner pipeline to build and deploy with Zephyr by adding a token to the CI/CD variables.
84+
85+
### Adding the GitLab CI/CD Variable
86+
87+
1. Create a full access token on your [Organization Server tokens page](#server-tokens-section) page
88+
2. Add it as a CI/CD variable in your GitLab project:
89+
90+
**Steps to add the token:**
91+
92+
1. Navigate to your GitLab project
93+
2. Go to **Settings** → **CI/CD**
94+
3. Expand the **Variables** section
95+
4. Click **Add variable**
96+
5. Configure the variable:
97+
- **Key**: `ZE_SERVER_TOKEN`
98+
- **Key**: `ZE_USER_EMAIL`
99+
- **Value**: Your Zephyr API token
100+
- **Type**: Variable
101+
- **Environment scope**: All (or specify specific environments)
102+
- **Protect variable**: ✅ Check if you want to use it only in protected branches
103+
- **Mask variable**: ✅ Check to hide the value in job logs
104+
105+
### Using the Token in GitLab CI/CD
106+
107+
In your `.gitlab-ci.yml` file, the token will be automatically available as an environment variable:
108+
109+
```yml title=".gitlab-ci.yml"
110+
build:
111+
stage: build
112+
script:
113+
- npm install
114+
- npm run build
115+
variables:
116+
ZE_SERVER_TOKEN: $ZE_SERVER_TOKEN
117+
ZE_USER_EMAIL: $ZE_USER_EMAIL
118+
```
119+
120+
For more explicit control, you can also reference it directly:
121+
122+
```yml title=".gitlab-ci.yml"
123+
deploy:
124+
stage: deploy
125+
script:
126+
- npm install
127+
- npm run build
128+
environment:
129+
name: production
130+
variables:
131+
ZE_SERVER_TOKEN: $ZE_SERVER_TOKEN
132+
ZE_USER_EMAIL: $ZE_USER_EMAIL
133+
```
134+
135+
### Authentication Behavior
136+
137+
When the Zephyr plugin detects the `ZE_SERVER_TOKEN` environment variable, it will automatically authenticate with the Zephyr API, bypassing the usual login step.
138+
139+
You'll see this confirmation in the console:
140+
141+
```shell
142+
ZEPHYR Token found in environment. Using secret token for authentication
143+
```
144+
145+
### Complete Pipeline Example
146+
147+
Here's a full GitLab CI/CD pipeline configured for Zephyr deployment:
148+
149+
```yml title=".gitlab-ci.yml"
150+
stages:
151+
- install
152+
- build
153+
- deploy
154+
155+
variables:
156+
npm_config_cache: '$CI_PROJECT_DIR/.npm'
157+
158+
cache:
159+
key: ${CI_COMMIT_REF_SLUG}
160+
paths:
161+
- .npm/
162+
- node_modules/
163+
164+
install:
165+
stage: install
166+
script:
167+
- npm ci --cache .npm --prefer-offline
168+
artifacts:
169+
paths:
170+
- node_modules/
171+
expire_in: 1 hour
172+
173+
build:
174+
stage: build
175+
script:
176+
- npm run build
177+
artifacts:
178+
paths:
179+
- dist/
180+
expire_in: 1 day
181+
variables:
182+
ZE_SERVER_TOKEN: $ZE_SERVER_TOKEN
183+
ZE_USER_EMAIL: $ZE_USER_EMAIL
184+
185+
deploy:
186+
stage: deploy
187+
script:
188+
- npm run deploy
189+
only:
190+
- main
191+
environment:
192+
name: production
193+
variables:
194+
ZE_SERVER_TOKEN: $ZE_SERVER_TOKEN
195+
ZE_USER_EMAIL: $ZE_USER_EMAIL
196+
```
197+
198+
## Security Notes
199+
200+
- Do not share server tokens publicly.
201+
- Rotate tokens regularly and revoke any that may be compromised.
202+
- Remember: server tokens provide organization-level access, so they are sensitive credentials.
203+
204+
## Troubleshooting
205+
206+
### Authentication Issues
207+
208+
**Token not found error:**
209+
210+
- Verify the variables names are exactly `ZE_SERVER_TOKEN` and `ZE_USER_EMAIL`
211+
- Ensure the variables are available in the environment where your job runs
212+
- Check that the token hasn't expired
213+
214+
### GitLab-Specific Issues
215+
216+
**Protected variables:**
217+
218+
- If using protected variables, ensure your pipeline runs on a protected branch or tag
219+
220+
**Masked variables:**
221+
222+
- Masked variables won't appear in job logs (recommended for security)
223+
- Temporarily unmask if you need to troubleshoot, then re-mask for production
224+
225+
**Variable scope:**
226+
227+
- Check that the variable scope matches your pipeline's environment requirements

‎docs/index.mdx‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -30,7 +30,8 @@ If you experience any issues, do jump in our [Discord](https://zephyr-cloud.io/d
3030
- **[Tags & Environments](/features/tags-environments)** - Detailed environment configuration and custom domains
3131
- **[Instant Rollbacks](/features/instant-rollbacks)** - Complex rollback scenarios and automated rollback triggers
3232
- **[Remote Dependencies](/features/remote-dependencies)** - Advanced dependency resolution and micro-frontend orchestration
33-
- **[CI/CD](/features/ci-cd)** - Detailed integration guides for different CI/CD platforms
33+
- **[CI/CD](/features/ci-cd-personal-token)** - Detailed integration guides for different CI/CD platforms with personal token
34+
- **[CI/CD](/features/ci-cd-server-token)** - Detailed integration guides for different CI/CD platforms with server token
3435
- **[Teams & Members](/features/teams-members)** - Team management, permissions, and collaboration features
3536
- **[Subscriptions](/features/subscriptions)** - Billing, usage monitoring, and plan management
3637

‎docs/public/org-settings-screen.webp‎

84 KB
Loading

‎docs/public/server-token-created-screen.webp‎

55.4 KB
Loading

‎docs/public/server-token-screen.webp‎

51.7 KB
Loading

‎docs/public/server-token-section-screen.webp‎

55.6 KB
Loading

‎docs/tutorials/metro.mdx‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -633,4 +633,5 @@ Now that you have Module Federation working with Metro, explore these advanced t
633633
- Check out [Remote Dependencies](/features/remote-dependencies) for advanced dependency configuration
634634
- Review [End-to-End Testing](/tutorials/e2e-testing) for testing federated applications
635635
- Understand [Versioning and Tags](/features/versioning-tags) for managing deployments
636-
- Set up [CI/CD pipelines](/features/ci-cd) for automated deployments
636+
- Set up [CI/CD pipelines](/features/ci-cd-personal-token) for automated deployments with Personal token
637+
- Set up [CI/CD pipelines](/features/ci-cd-server-token) for automated deployments with Server token

‎rspress.config.ts‎

Lines changed: 8 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -82,12 +82,16 @@ const sidebar: Sidebar = {
8282
link: '/features/remote-dependencies',
8383
},
8484
{
85-
text: 'Environment Overrides',
86-
link: '/features/environment-overrides',
85+
text: 'CI/CD - Personal token',
86+
link: '/features/ci-cd-personal-token',
87+
},
88+
{
89+
text: 'CI/CD - Server token',
90+
link: '/features/ci-cd-server-token',
8791
},
8892
{
89-
text: 'CI/CD',
90-
link: '/features/ci-cd',
93+
text: 'Environment Overrides',
94+
link: '/features/environment-overrides',
9195
},
9296
{
9397
text: 'Teams & Members',

0 commit comments

Comments
 (0)