You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: CONTRIBUTING.md
+12Lines changed: 12 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -38,6 +38,18 @@ npm run package
38
38
npm test
39
39
```
40
40
41
+
## Validation
42
+
43
+
The action uses [Zod](https://zod.dev/) for schema validation, automatically validating code.json in two scenarios:
44
+
45
+
### 1. Before Generation
46
+
47
+
Every time the action generates or updates code.json (via schedule or workflow_dispatch), it validates the output before creating a PR or pushing. If validation fails, no changes are made.
48
+
49
+
### 2. On PR Edits
50
+
51
+
When the `pull_request` trigger is configured, the action validates code.json whenever it's edited in a PR. This ensures users cannot accidentally merge invalid JSON.
52
+
41
53
### Workflow and Branching
42
54
43
55
We follow the [GitHub Flow Workflow](https://guides.github.com/introduction/flow/):
Copy file name to clipboardExpand all lines: README.md
+86-39Lines changed: 86 additions & 39 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -6,53 +6,58 @@ A GitHub Action that automatically generates and maintains code.json files for f
6
6
7
7
This project provides a GitHub Action that helps federal agencies maintain their code.json files, which are required for compliance with the Federal Source Code Policy. The action automatically calculates and updates various metadata fields including labor hours, programming languages used, repository information, and timestamps. It can either create pull requests or push directly to branches (with appropriate permissions), making it easier to keep code.json files accurate and up-to-date.
8
8
9
-
## Inputs
9
+
## How It Works
10
10
11
-
```yaml
12
-
GITHUB_TOKEN:
13
-
description: "GitHub token used for API access and PR creation"
14
-
required: true
15
-
default: ${{ github.token }}
16
-
17
-
BRANCH:
18
-
description: "Name of the branch to update"
19
-
required: false
11
+
**Automatic Generation**
20
12
21
-
SKIP_PR:
22
-
description: "Try to push directly to branch first, fallback to PR if it fails. Requires ADMIN_TOKEN."
23
-
required: false
24
-
default: "false"
13
+
- The action calculates metadata and creates a PR or pushes directly
14
+
- Users can then fill in manual fields by editing the PR
25
15
26
-
ADMIN_TOKEN:
27
-
description: "Personal Access Token with admin/write privileges for direct push. Required when SKIP_PR is true."
28
-
required: false
29
-
```
16
+
**PR Validation**
30
17
31
-
## Outputs
18
+
- When users edit code.json in a PR, validation runs automatically on every commit
19
+
- The PR cannot be merged if validation fails (when branch protection is enabled)
20
+
- Error messages help users fix issues quickly
21
+
- Validation ensures only valid code.json reaches your main branch
32
22
33
-
```yaml
34
-
updated:
35
-
description: "Boolean indicating whether code.json was updated"
36
-
pr_url:
37
-
description: "URL of the created pull request if changes were made via PR"
38
-
commit_sha:
39
-
description: "SHA of the commit if pushed directly to branch"
40
-
method_used:
41
-
description: "Method used for the update: 'direct_push' or 'pull_request'"
42
-
```
23
+
**Important:** For direct push mode, users should always create PRs when manually editing code.json to ensure validation runs. Direct edits to the main branch will not be validated by this action.
43
24
44
25
## Workflow Examples
45
26
46
27
### Option 1: Direct Push
47
28
48
-
This approach tries to push directly to the branch using a Personal Access Token, but falls back to creating a pull request if the direct push fails.
29
+
This approach tries to push directly to the branch using a Personal Access Token, but falls back to creating a pull request if the direct push fails. When users need to edit code.json, they should create a PR which will automatically validate their changes. Refer to this [section](https://github.com/DSACMS/automated-codejson-generator?tab=readme-ov-file#setting-up-personal-access-token-pat) for a guide to create the necessary Personal Access Token.
30
+
31
+
#### Direct Push Mode Limitations
32
+
33
+
**Important:** Direct push mode (`SKIP_PR: "true"`) will fall back to creating a pull request if:
34
+
- Branch protection rules are enabled on the target branch
35
+
- The PAT doesn't have sufficient permissions
36
+
- Any other push restriction exists
37
+
38
+
This is expected behavior. If you need all updates to go through pull requests, use `SKIP_PR: "false"`.
39
+
40
+
##### When Direct Push Works
41
+
- No branch protection on target branch
42
+
- PAT has write access
43
+
- No other repository restrictions
44
+
45
+
##### When It Falls Back to PR
46
+
- Any branch protection enabled
47
+
- Any push restrictions
48
+
49
+
**Recommendation:** For repositories with branch protection, use `SKIP_PR: "false"` to always create pull requests.
49
50
50
51
```yaml
51
52
name: Update Code.json
52
53
on:
53
54
schedule:
54
55
- cron: 0 0 1 * * # First day of every month
55
56
workflow_dispatch:
57
+
pull_request:
58
+
types: [opened, synchronize]
59
+
paths:
60
+
- "code.json"
56
61
57
62
permissions:
58
63
contents: write
@@ -73,7 +78,7 @@ jobs:
73
78
uses: DSACMS/automated-codejson-generator@v1.2.0
74
79
with:
75
80
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
76
-
ADMIN_TOKEN: ${{ secrets.ADMIN_PAT }} # PAT with admin/push permissions
81
+
ADMIN_TOKEN: ${{ secrets.ADMIN_PAT }} # PAT with admin/push permissions
77
82
BRANCH: "main"
78
83
SKIP_PR: "true"
79
84
@@ -89,14 +94,18 @@ jobs:
89
94
90
95
### Option 2: Pull Request Only
91
96
92
-
This approach always creates a pull request, ensuring code review for all changes.
97
+
This approach always creates a pull request for both automatic generation and validation of manual edits, ensuring code review for all changes.
93
98
94
99
```yaml
95
100
name: Update Code.json
96
101
on:
97
102
schedule:
98
103
- cron: 0 0 1 * * # First day of every month
99
104
workflow_dispatch:
105
+
pull_request:
106
+
types: [opened, synchronize]
107
+
paths:
108
+
- "code.json"
100
109
101
110
permissions:
102
111
contents: write
@@ -113,11 +122,49 @@ jobs:
113
122
fetch-depth: 0
114
123
115
124
- name: Update code.json
116
-
uses: DSACMS/automated-codejson-generator@latest
125
+
uses: DSACMS/automated-codejson-generator@v1.2.0
117
126
with:
118
127
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
119
128
BRANCH: "main"
120
-
SKIP_PR: "false"
129
+
SKIP_PR: "false"
130
+
```
131
+
132
+
### Inputs
133
+
134
+
```yaml
135
+
GITHUB_TOKEN:
136
+
description: "GitHub token used for API access and PR creation"
137
+
required: true
138
+
default: ${{ github.token }}
139
+
140
+
BRANCH:
141
+
description: "Name of the branch to update"
142
+
required: false
143
+
144
+
SKIP_PR:
145
+
description: "Try to push directly to branch first, fallback to PR if it fails. Requires ADMIN_TOKEN."
146
+
required: false
147
+
default: "false"
148
+
149
+
ADMIN_TOKEN:
150
+
description: "Personal Access Token with admin/write privileges for direct push. Required when SKIP_PR is true."
151
+
required: false
152
+
```
153
+
154
+
### Outputs
155
+
156
+
```yaml
157
+
updated:
158
+
description: "Boolean indicating whether code.json was updated"
159
+
160
+
pr_url:
161
+
description: "URL of the created pull request if changes were made via PR"
162
+
163
+
commit_sha:
164
+
description: "SHA of the commit if pushed directly to branch"
165
+
166
+
method_used:
167
+
description: "Method used for the update: 'direct_push' or 'pull_request'"
121
168
```
122
169
123
170
## Setting Up Personal Access Token (PAT)
@@ -128,10 +175,10 @@ To use the direct push functionality, you'll need to create a Personal Access To
128
175
129
176
1. **Go to GitHub Settings**: Navigate to your GitHub account settings
130
177
2. **Developer Settings**: Click on "Developer settings" in the left sidebar
131
-
3. **Personal Access Tokens**: Choose "Tokens (classic)" or "Fine-grained tokens"
@@ -174,7 +220,7 @@ The automated code.json generator calculates specific fields by analyzing your r
174
220
175
221
**dateLastModified**: This uses your repository's last update timestamp, reflecting the most recent changes. No configuration needed.
176
222
177
-
**dateMetaDataLastUpdated**: The generator sets this to the current timestamp each time it runs, providing a record of when the metadata was last refreshed. No configuration needed.
223
+
**dateMetadataLastUpdated**: The generator sets this to the current timestamp each time it runs, providing a record of when the metadata was last refreshed. No configuration needed.
178
224
179
225
**feedbackMechanism**: The repository's issues URL in the format of {repositoryURL}/issues. If you already have a code.json file with existing feedback mechanisms, the generator preserves those values. No configuration needed.
180
226
@@ -214,6 +260,7 @@ An up-to-date list of core team members can be found in [MAINTAINERS.md](MAINTAI
214
260
.
215
261
├── src/
216
262
│ ├── model.ts # TypeScript interfaces for code.json schema
263
+
│ ├── validation.ts # Zod schema definitions and validation logic
217
264
│ ├── main.ts # Main action logic
218
265
│ ├── helper.ts # Helper functions for GitHub API interactions
0 commit comments