Skip to content

Commit 1cab7e2

Browse files
kiumakiuma
committed
first commit
0 parents  commit 1cab7e2

17 files changed

+12726
-0
lines changed

‎.github/workflows/README.md‎

Lines changed: 164 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,164 @@
1+
# GitHub Workflows
2+
3+
This directory contains GitHub Actions workflows for the `nestjs-offline-oauth2` package.
4+
5+
## Workflows
6+
7+
### 1. CI Workflow (`ci.yml`)
8+
9+
**Triggers:**
10+
- Push to `main` or `develop` branches
11+
- Pull requests to `main` or `develop` branches
12+
13+
**What it does:**
14+
- Tests the package on Node.js 18.x and 20.x
15+
- Runs linting and formatting checks
16+
- Builds the project and verifies output
17+
- Validates package.json configuration
18+
- Performs a dry-run publish to ensure package is ready
19+
- Runs security audits
20+
21+
### 2. NPM Publish Workflow (`npm-publish.yml`)
22+
23+
**Triggers:**
24+
- **Automatic**: When a GitHub release is published
25+
- **Manual**: Workflow dispatch with version bump options
26+
27+
**What it does:**
28+
- Installs dependencies and runs quality checks
29+
- Builds the project
30+
- Bumps version (manual trigger only)
31+
- Creates git tag (manual trigger only)
32+
- Publishes to NPM
33+
- Creates GitHub release (manual trigger only)
34+
35+
## Setup Instructions
36+
37+
### 1. NPM Token Setup
38+
39+
1. Go to [npmjs.com](https://www.npmjs.com) and log in
40+
2. Navigate to your profile → Access Tokens
41+
3. Generate a new token with "Automation" or "Publish" permissions
42+
4. In your GitHub repository, go to Settings → Secrets and variables → Actions
43+
5. Add a new repository secret named `NPM_TOKEN` with your token value
44+
45+
### 2. Repository Permissions
46+
47+
Ensure your repository has the following permissions:
48+
- Actions: Read and write permissions
49+
- Contents: Write permissions (for creating releases and tags)
50+
- Metadata: Read permissions
51+
52+
To set these:
53+
1. Go to Settings → Actions → General
54+
2. Under "Workflow permissions", select "Read and write permissions"
55+
3. Check "Allow GitHub Actions to create and approve pull requests"
56+
57+
## Usage
58+
59+
### Publishing a New Version
60+
61+
#### Method 1: Manual Workflow Dispatch (Recommended)
62+
63+
1. Go to Actions tab in your GitHub repository
64+
2. Select "Publish to NPM" workflow
65+
3. Click "Run workflow"
66+
4. Choose the version bump type:
67+
- `patch`: Bug fixes (1.0.0 → 1.0.1)
68+
- `minor`: New features (1.0.0 → 1.1.0)
69+
- `major`: Breaking changes (1.0.0 → 2.0.0)
70+
5. Click "Run workflow"
71+
72+
This will:
73+
- Bump the version in package.json
74+
- Create a git commit and tag
75+
- Publish to NPM
76+
- Create a GitHub release
77+
78+
#### Method 2: GitHub Release
79+
80+
1. Go to Releases in your repository
81+
2. Click "Create a new release"
82+
3. Create a new tag (e.g., `v1.0.1`)
83+
4. Add release notes
84+
5. Publish the release
85+
86+
This will automatically trigger the NPM publish workflow.
87+
88+
### Checking Build Status
89+
90+
- All pull requests will automatically run the CI workflow
91+
- Check the Actions tab to see workflow status
92+
- Green checkmarks indicate successful builds
93+
- Red X marks indicate failures that need to be fixed
94+
95+
## Workflow Files Explained
96+
97+
### CI Workflow Features
98+
99+
- **Multi-Node Testing**: Tests on Node.js 18.x and 20.x
100+
- **Code Quality**: Runs ESLint and Prettier checks
101+
- **Build Verification**: Ensures TypeScript compilation works
102+
- **Package Validation**: Checks package.json structure
103+
- **Security**: Runs npm audit for vulnerabilities
104+
- **Dry Run**: Tests publishing without actually publishing
105+
106+
### Publish Workflow Features
107+
108+
- **Quality Gates**: Runs linting and building before publishing
109+
- **Version Management**: Automatic version bumping for manual triggers
110+
- **Git Integration**: Creates commits and tags automatically
111+
- **NPM Publishing**: Publishes with public access
112+
- **Release Creation**: Generates GitHub releases with changelog
113+
- **Error Handling**: Validates build output before publishing
114+
115+
## Troubleshooting
116+
117+
### Common Issues
118+
119+
1. **NPM_TOKEN not working**
120+
- Ensure the token has correct permissions
121+
- Check token hasn't expired
122+
- Verify secret name is exactly `NPM_TOKEN`
123+
124+
2. **Permission denied errors**
125+
- Check repository workflow permissions
126+
- Ensure GITHUB_TOKEN has write access
127+
128+
3. **Build failures**
129+
- Check TypeScript compilation locally
130+
- Ensure all dependencies are properly declared
131+
- Verify dist folder is created correctly
132+
133+
4. **Version conflicts**
134+
- Ensure the version doesn't already exist on NPM
135+
- Check if git tags already exist
136+
137+
### Manual Recovery
138+
139+
If workflows fail and you need to publish manually:
140+
141+
```bash
142+
# Build the project
143+
npm run build
144+
145+
# Publish to NPM
146+
npm publish --access public
147+
```
148+
149+
## Best Practices
150+
151+
1. **Always test locally** before pushing changes
152+
2. **Use semantic versioning** for version bumps
153+
3. **Write meaningful commit messages** for version bumps
154+
4. **Test the package** after publishing to ensure it works
155+
5. **Monitor workflow runs** and fix issues promptly
156+
6. **Keep dependencies updated** to avoid security issues
157+
158+
## Security Considerations
159+
160+
- Never commit NPM tokens to the repository
161+
- Regularly rotate access tokens
162+
- Monitor package downloads for unusual activity
163+
- Keep dependencies updated to avoid vulnerabilities
164+
- Use `npm audit` regularly to check for security issues

‎.github/workflows/ci.yml‎

Lines changed: 90 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,90 @@
1+
name: CI
2+
3+
on:
4+
push:
5+
branches: [main]
6+
pull_request:
7+
branches: [main]
8+
9+
jobs:
10+
test:
11+
runs-on: ubuntu-latest
12+
13+
strategy:
14+
matrix:
15+
node-version: [18.x, 20.x, 22.x]
16+
17+
steps:
18+
- name: Checkout code
19+
uses: actions/checkout@v4
20+
21+
- name: Setup Node.js ${{ matrix.node-version }}
22+
uses: actions/setup-node@v4
23+
with:
24+
node-version: ${{ matrix.node-version }}
25+
cache: 'npm'
26+
27+
- name: Install dependencies
28+
run: npm ci
29+
30+
- name: Run linting
31+
run: npm run lint
32+
33+
- name: Run formatting check
34+
run: npm run format -- --check
35+
36+
- name: Build project
37+
run: npm run build
38+
39+
- name: Verify build output
40+
run: |
41+
if [ ! -d "dist" ]; then
42+
echo "Build failed: dist directory not found"
43+
exit 1
44+
fi
45+
if [ ! -f "dist/index.js" ]; then
46+
echo "Build failed: main file not found"
47+
exit 1
48+
fi
49+
if [ ! -f "dist/index.d.ts" ]; then
50+
echo "Build failed: type definitions not found"
51+
exit 1
52+
fi
53+
echo "✅ Build verification passed"
54+
55+
- name: Check package.json
56+
run: |
57+
node -e "
58+
const pkg = require('./package.json');
59+
if (!pkg.name) throw new Error('Package name is required');
60+
if (!pkg.version) throw new Error('Package version is required');
61+
if (!pkg.main) throw new Error('Package main entry is required');
62+
if (!pkg.types) throw new Error('Package types entry is required');
63+
if (!pkg.files || !pkg.files.includes('dist')) throw new Error('Package files must include dist');
64+
console.log('✅ Package.json validation passed');
65+
"
66+
67+
- name: Dry run publish
68+
run: npm publish --dry-run
69+
70+
security:
71+
runs-on: ubuntu-latest
72+
73+
steps:
74+
- name: Checkout code
75+
uses: actions/checkout@v4
76+
77+
- name: Setup Node.js
78+
uses: actions/setup-node@v4
79+
with:
80+
node-version: '18'
81+
cache: 'npm'
82+
83+
- name: Install dependencies
84+
run: npm ci
85+
86+
- name: Run security audit
87+
run: npm audit --audit-level=moderate
88+
89+
- name: Check for known vulnerabilities
90+
run: npm audit --audit-level=high --production

‎.github/workflows/npm-publish.yml‎

Lines changed: 137 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,137 @@
1+
name: Publish to NPM
2+
3+
on:
4+
release:
5+
types: [published]
6+
workflow_dispatch:
7+
inputs:
8+
version_type:
9+
description: 'Version bump type'
10+
required: true
11+
default: 'patch'
12+
type: choice
13+
options:
14+
- patch
15+
- minor
16+
- major
17+
18+
jobs:
19+
publish:
20+
runs-on: ubuntu-latest
21+
22+
steps:
23+
- name: Checkout code
24+
uses: actions/checkout@v4
25+
with:
26+
fetch-depth: 0
27+
token: ${{ secrets.GITHUB_TOKEN }}
28+
29+
- name: Setup Node.js
30+
uses: actions/setup-node@v4
31+
with:
32+
node-version: '18'
33+
registry-url: 'https://registry.npmjs.org'
34+
35+
- name: Cache node modules
36+
uses: actions/cache@v4
37+
with:
38+
path: ~/.npm
39+
key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
40+
restore-keys: |
41+
${{ runner.os }}-node-
42+
43+
- name: Install dependencies
44+
run: npm ci
45+
46+
- name: Run linting
47+
run: npm run lint
48+
49+
- name: Build project
50+
run: npm run build
51+
52+
- name: Verify build output
53+
run: |
54+
if [ ! -d "dist" ]; then
55+
echo "Build failed: dist directory not found"
56+
exit 1
57+
fi
58+
if [ ! -f "dist/index.js" ]; then
59+
echo "Build failed: main file not found"
60+
exit 1
61+
fi
62+
if [ ! -f "dist/index.d.ts" ]; then
63+
echo "Build failed: type definitions not found"
64+
exit 1
65+
fi
66+
67+
- name: Bump version and create tag (manual trigger only)
68+
if: github.event_name == 'workflow_dispatch'
69+
id: version
70+
run: |
71+
git config --local user.email "[email protected]"
72+
git config --local user.name "GitHub Action"
73+
74+
# Bump version
75+
npm version ${{ github.event.inputs.version_type }} --no-git-tag-version
76+
77+
# Get new version
78+
NEW_VERSION=$(node -p "require('./package.json').version")
79+
echo "version=$NEW_VERSION" >> $GITHUB_OUTPUT
80+
81+
# Commit changes
82+
git add package.json package-lock.json
83+
git commit -m "chore: bump version to $NEW_VERSION"
84+
85+
# Create and push tag
86+
git tag "v$NEW_VERSION"
87+
git push origin main
88+
git push origin "v$NEW_VERSION"
89+
90+
- name: Get version for release trigger
91+
if: github.event_name == 'release'
92+
id: release_version
93+
run: |
94+
VERSION=$(echo "${{ github.event.release.tag_name }}" | sed 's/^v//')
95+
echo "version=$VERSION" >> $GITHUB_OUTPUT
96+
97+
- name: Publish to NPM
98+
run: npm publish --access public
99+
env:
100+
NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
101+
102+
- name: Create GitHub Release (manual trigger only)
103+
if: github.event_name == 'workflow_dispatch'
104+
uses: actions/create-release@v1
105+
env:
106+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
107+
with:
108+
tag_name: v${{ steps.version.outputs.version }}
109+
release_name: Release v${{ steps.version.outputs.version }}
110+
body: |
111+
## Release v${{ steps.version.outputs.version }}
112+
113+
This release was automatically generated from the workflow.
114+
115+
### Changes
116+
- Version bump (${{ github.event.inputs.version_type }})
117+
- Updated package to v${{ steps.version.outputs.version }}
118+
119+
### Installation
120+
```bash
121+
npm install nestjs-offline-oauth2@${{ steps.version.outputs.version }}
122+
```
123+
124+
### Documentation
125+
Please refer to the [README](https://github.com/RedSoftwareSystems/nestjs-offline-oauth2/blob/main/README.md) for usage instructions.
126+
draft: false
127+
prerelease: false
128+
129+
- name: Post-publish notification
130+
run: |
131+
if [ "${{ github.event_name }}" == "workflow_dispatch" ]; then
132+
VERSION="${{ steps.version.outputs.version }}"
133+
else
134+
VERSION="${{ steps.release_version.outputs.version }}"
135+
fi
136+
echo "✅ Successfully published nestjs-offline-oauth2@$VERSION to NPM"
137+
echo "📦 Package URL: https://www.npmjs.com/package/nestjs-offline-oauth2"

0 commit comments

Comments
 (0)