Skip to content

Commit fdd6f7c

Browse files
moniyazimoniyazi
committed
Add usage guide
1 parent d1cc4c8 commit fdd6f7c

File tree

2 files changed

+291
-5
lines changed

2 files changed

+291
-5
lines changed

‎README.md‎

Lines changed: 33 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,7 @@ jobs:
2929
pull-requests: write
3030
steps:
3131
- uses: actions/checkout@v4
32-
- uses: apisec-bolt/code-discovery-action@v1
32+
- uses: apisec-inc/apisec-bolt-code-discovery-github-action@v0.1.0
3333
with:
3434
api-endpoint: ${{ secrets.API_DISCOVERY_ENDPOINT }}
3535
api-token: ${{ secrets.API_DISCOVERY_TOKEN }}
@@ -52,7 +52,7 @@ jobs:
5252
pull-requests: write
5353
steps:
5454
- uses: actions/checkout@v4
55-
- uses: apisec-bolt/code-discovery-action@v1
55+
- uses: apisec-inc/apisec-bolt-code-discovery-github-action@v0.1.0
5656
with:
5757
api-endpoint: ${{ secrets.API_DISCOVERY_ENDPOINT }}
5858
api-token: ${{ secrets.API_DISCOVERY_TOKEN }}
@@ -63,7 +63,7 @@ jobs:
6363
### Custom Configuration
6464
6565
```yaml
66-
- uses: apisec-bolt/code-discovery-action@v1
66+
- uses: apisec-inc/apisec-bolt-code-discovery-github-action@v0.1.0
6767
with:
6868
api-endpoint: ${{ secrets.API_DISCOVERY_ENDPOINT }}
6969
api-token: ${{ secrets.API_DISCOVERY_TOKEN }}
@@ -74,7 +74,7 @@ jobs:
7474
### Dry Run (Testing)
7575
7676
```yaml
77-
- uses: apisec-bolt/code-discovery-action@v1
77+
- uses: apisec-inc/apisec-bolt-code-discovery-github-action@v0.1.0
7878
with:
7979
api-endpoint: ${{ secrets.API_DISCOVERY_ENDPOINT }}
8080
api-token: ${{ secrets.API_DISCOVERY_TOKEN }}
@@ -171,5 +171,33 @@ MIT License - see [LICENSE](LICENSE) file for details.
171171

172172
## Support
173173

174-
For issues and questions, please open an issue in the [repository](https://github.com/apisec-bolt/code-discovery-action).
174+
For issues and questions, please open an issue in the [repository](https://github.com/apisec-inc/apisec-bolt-code-discovery-github-action).
175+
176+
## Quick Start
177+
178+
1. **Add workflow file** `.github/workflows/api-discovery.yml`:
179+
```yaml
180+
name: API Discovery
181+
on:
182+
push:
183+
branches: [main]
184+
jobs:
185+
discover:
186+
runs-on: ubuntu-latest
187+
permissions:
188+
contents: write
189+
pull-requests: write
190+
steps:
191+
- uses: actions/checkout@v4
192+
- uses: apisec-inc/apisec-bolt-code-discovery-github-action@v0.1.0
193+
with:
194+
api-endpoint: ${{ secrets.API_DISCOVERY_ENDPOINT }}
195+
api-token: ${{ secrets.API_DISCOVERY_TOKEN }}
196+
```
197+
198+
2. **Configure secrets** in repository Settings → Secrets:
199+
- `API_DISCOVERY_ENDPOINT` - Your API endpoint URL
200+
- `API_DISCOVERY_TOKEN` - Your Bearer token
201+
202+
3. **Push to trigger** - The action will run automatically!
175203

‎USAGE_GUIDE.md‎

Lines changed: 258 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,258 @@
1+
# How to Use Code Discovery GitHub Action
2+
3+
## Quick Start
4+
5+
Add this workflow to your repository at `.github/workflows/api-discovery.yml`:
6+
7+
```yaml
8+
name: API Discovery
9+
10+
on:
11+
push:
12+
branches: [main]
13+
14+
jobs:
15+
discover:
16+
runs-on: ubuntu-latest
17+
permissions:
18+
contents: write
19+
pull-requests: write
20+
steps:
21+
- uses: actions/checkout@v4
22+
- uses: apisec-inc/apisec-bolt-code-discovery-github-action@v0.1.0
23+
with:
24+
api-endpoint: ${{ secrets.API_DISCOVERY_ENDPOINT }}
25+
api-token: ${{ secrets.API_DISCOVERY_TOKEN }}
26+
```
27+
28+
## Step-by-Step Setup
29+
30+
### 1. Create Workflow File
31+
32+
Create `.github/workflows/api-discovery.yml` in your repository:
33+
34+
```yaml
35+
name: API Discovery
36+
37+
on:
38+
push:
39+
branches: [main]
40+
schedule:
41+
- cron: '0 2 * * *' # Daily at 2 AM UTC
42+
workflow_dispatch: # Allow manual trigger
43+
44+
jobs:
45+
discover:
46+
runs-on: ubuntu-latest
47+
permissions:
48+
contents: write # Required to commit files
49+
pull-requests: write # Required to create PRs
50+
51+
steps:
52+
- name: Checkout code
53+
uses: actions/checkout@v4
54+
55+
- name: Run Code Discovery
56+
uses: apisec-inc/apisec-bolt-code-discovery-github-action@v0.1.0
57+
with:
58+
api-endpoint: ${{ secrets.API_DISCOVERY_ENDPOINT }}
59+
api-token: ${{ secrets.API_DISCOVERY_TOKEN }}
60+
pr-title: 'chore: update OpenAPI specification'
61+
pr-body: 'Automatically generated OpenAPI specification from code discovery'
62+
```
63+
64+
### 2. Configure Secrets
65+
66+
Go to your repository **Settings → Secrets and variables → Actions** and add:
67+
68+
- **`API_DISCOVERY_ENDPOINT`**: Your API endpoint URL (e.g., `https://api.dev.apisecapps.com`)
69+
- **`API_DISCOVERY_TOKEN`**: Your Bearer token for authentication
70+
71+
### 3. Commit and Push
72+
73+
```bash
74+
git add .github/workflows/api-discovery.yml
75+
git commit -m "Add API Discovery workflow"
76+
git push
77+
```
78+
79+
## Usage Examples
80+
81+
### Basic Usage (Push Trigger)
82+
83+
Runs automatically on every push to `main`:
84+
85+
```yaml
86+
on:
87+
push:
88+
branches: [main]
89+
```
90+
91+
### Scheduled Runs
92+
93+
Runs daily at 2 AM UTC:
94+
95+
```yaml
96+
on:
97+
schedule:
98+
- cron: '0 2 * * *'
99+
```
100+
101+
### Manual Trigger
102+
103+
Allows manual triggering from GitHub Actions UI:
104+
105+
```yaml
106+
on:
107+
workflow_dispatch:
108+
```
109+
110+
### Custom Repository Path
111+
112+
If your API code is in a subdirectory:
113+
114+
```yaml
115+
- uses: apisec-inc/apisec-bolt-code-discovery-github-action@v0.1.0
116+
with:
117+
api-endpoint: ${{ secrets.API_DISCOVERY_ENDPOINT }}
118+
api-token: ${{ secrets.API_DISCOVERY_TOKEN }}
119+
repo-path: './backend'
120+
```
121+
122+
### Custom Configuration File
123+
124+
If you have a custom config file:
125+
126+
```yaml
127+
- uses: apisec-inc/apisec-bolt-code-discovery-github-action@v0.1.0
128+
with:
129+
api-endpoint: ${{ secrets.API_DISCOVERY_ENDPOINT }}
130+
api-token: ${{ secrets.API_DISCOVERY_TOKEN }}
131+
config-path: './backend/.codediscovery.yml'
132+
```
133+
134+
### Dry Run (Testing)
135+
136+
Test without uploading to API:
137+
138+
```yaml
139+
- uses: apisec-inc/apisec-bolt-code-discovery-github-action@v0.1.0
140+
with:
141+
api-endpoint: ${{ secrets.API_DISCOVERY_ENDPOINT }}
142+
api-token: ${{ secrets.API_DISCOVERY_TOKEN }}
143+
dry-run: true
144+
```
145+
146+
### Custom PR Title and Body
147+
148+
```yaml
149+
- uses: apisec-inc/apisec-bolt-code-discovery-github-action@v0.1.0
150+
with:
151+
api-endpoint: ${{ secrets.API_DISCOVERY_ENDPOINT }}
152+
api-token: ${{ secrets.API_DISCOVERY_TOKEN }}
153+
pr-title: 'chore: update OpenAPI specification [skip ci]'
154+
pr-body: |
155+
This PR contains automatically generated OpenAPI specification.
156+
157+
Generated by Code Discovery GitHub Action.
158+
```
159+
160+
## Using Action Outputs
161+
162+
Access outputs from the action:
163+
164+
```yaml
165+
- uses: apisec-inc/apisec-bolt-code-discovery-github-action@v0.1.0
166+
id: discovery
167+
with:
168+
api-endpoint: ${{ secrets.API_DISCOVERY_ENDPOINT }}
169+
api-token: ${{ secrets.API_DISCOVERY_TOKEN }}
170+
171+
- name: Display results
172+
run: |
173+
echo "Spec path: ${{ steps.discovery.outputs.spec-path }}"
174+
echo "Application ID: ${{ steps.discovery.outputs.application-id }}"
175+
echo "Instance ID: ${{ steps.discovery.outputs.instance-id }}"
176+
echo "PR URL: ${{ steps.discovery.outputs.pr-url }}"
177+
```
178+
179+
## What Happens When It Runs
180+
181+
1. **Installs CLI** - Installs Code Discovery CLI (v0.2.0)
182+
2. **Configures API** - Sets up credentials from secrets
183+
3. **Discovers Endpoints** - Scans your codebase for API endpoints
184+
4. **Generates OpenAPI Spec** - Creates `apisec-bolt-code-discovery/openapi_spec.yaml`
185+
5. **Uploads to API** - Sends spec to your API security platform
186+
6. **Creates PR** - Creates a pull request with the generated files
187+
188+
## Generated Files
189+
190+
The action creates files in `apisec-bolt-code-discovery/`:
191+
192+
- `openapi_spec.yaml` - OpenAPI 3.0 specification
193+
- `state.yaml` - State file (tracks application/instance IDs)
194+
195+
Both files are automatically committed to the pull request.
196+
197+
## Version Pinning
198+
199+
**Recommended:** Pin to a specific version for stability:
200+
201+
```yaml
202+
uses: apisec-inc/apisec-bolt-code-discovery-github-action@v0.1.0
203+
```
204+
205+
**Latest:** Use `@main` for latest (not recommended for production):
206+
207+
```yaml
208+
uses: apisec-inc/apisec-bolt-code-discovery-github-action@main
209+
```
210+
211+
## Troubleshooting
212+
213+
### Action Fails to Create PR
214+
215+
**Check permissions:**
216+
```yaml
217+
permissions:
218+
contents: write
219+
pull-requests: write
220+
```
221+
222+
### No Endpoints Discovered
223+
224+
- Check if your framework is supported (Spring Boot, Micronaut, FastAPI, Flask, ASP.NET Core)
225+
- Verify `repo-path` points to the correct directory
226+
- Check action logs for detection messages
227+
228+
### API Upload Fails
229+
230+
- Verify `API_DISCOVERY_ENDPOINT` and `API_DISCOVERY_TOKEN` secrets are set correctly
231+
- Check token hasn't expired
232+
- Review action logs for API error messages
233+
234+
### PR Already Exists
235+
236+
The action handles this automatically - it will reuse existing PRs for the same branch.
237+
238+
## Required Permissions
239+
240+
The action requires these GitHub permissions:
241+
242+
```yaml
243+
permissions:
244+
contents: write # To commit generated files
245+
pull-requests: write # To create pull requests
246+
```
247+
248+
## Supported Frameworks
249+
250+
- **Java**: Spring Boot, Micronaut
251+
- **Python**: FastAPI, Flask
252+
- **.NET**: ASP.NET Core
253+
254+
## More Information
255+
256+
- [Action Repository](https://github.com/apisec-inc/apisec-bolt-code-discovery-github-action)
257+
- [Release v0.1.0](https://github.com/apisec-inc/apisec-bolt-code-discovery-github-action/releases/tag/v0.1.0)
258+

0 commit comments

Comments
 (0)