projen 0.67.55 → 0.67.56

package/.jsii

@@ -112,7 +112,7 @@
     "projen.github.workflows": {
       "locationInModule": {
         "filename": "src/github/index.ts",
-        "line": 18
+        "line": 19
       },
       "symbolId": "src/github/workflows-model:"
     },
@@ -20066,7 +20066,7 @@
         },
         "locationInModule": {
           "filename": "src/github/github.ts",
-          "line": 91
+          "line": 97
         },
         "parameters": [
           {
@@ -20087,7 +20087,7 @@
       "kind": "class",
       "locationInModule": {
         "filename": "src/github/github.ts",
-        "line": 65
+        "line": 66
       },
       "methods": [
         {
@@ -20097,7 +20097,7 @@
           },
           "locationInModule": {
             "filename": "src/github/github.ts",
-            "line": 70
+            "line": 71
           },
           "name": "of",
           "parameters": [
@@ -20122,7 +20122,7 @@
           },
           "locationInModule": {
             "filename": "src/github/github.ts",
-            "line": 148
+            "line": 156
           },
           "name": "addDependabot",
           "parameters": [
@@ -20146,7 +20146,7 @@
           },
           "locationInModule": {
             "filename": "src/github/github.ts",
-            "line": 144
+            "line": 152
           },
           "name": "addPullRequestTemplate",
           "parameters": [
@@ -20173,7 +20173,7 @@
           },
           "locationInModule": {
             "filename": "src/github/github.ts",
-            "line": 139
+            "line": 147
           },
           "name": "addWorkflow",
           "parameters": [
@@ -20201,7 +20201,7 @@
           },
           "locationInModule": {
             "filename": "src/github/github.ts",
-            "line": 156
+            "line": 164
           },
           "name": "tryFindWorkflow",
           "parameters": [
@@ -20226,6 +20226,20 @@
       "name": "GitHub",
       "namespace": "github",
       "properties": [
+        {
+          "docs": {
+            "stability": "experimental"
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "src/github/github.ts",
+            "line": 95
+          },
+          "name": "actions",
+          "type": {
+            "fqn": "projen.github.GitHubActionsProvider"
+          }
+        },
         {
           "docs": {
             "stability": "experimental",
@@ -20234,7 +20248,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/github/github.ts",
-            "line": 89
+            "line": 90
           },
           "name": "projenCredentials",
           "type": {
@@ -20249,7 +20263,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/github/github.ts",
-            "line": 126
+            "line": 134
           },
           "name": "workflows",
           "type": {
@@ -20269,7 +20283,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/github/github.ts",
-            "line": 84
+            "line": 85
           },
           "name": "workflowsEnabled",
           "type": {
@@ -20285,7 +20299,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/github/github.ts",
-            "line": 79
+            "line": 80
           },
           "name": "mergify",
           "optional": true,
@@ -20296,6 +20310,80 @@
       ],
       "symbolId": "src/github/github:GitHub"
     },
+    "projen.github.GitHubActionsProvider": {
+      "assembly": "projen",
+      "docs": {
+        "stability": "experimental",
+        "summary": "Manage the versions used for GitHub Actions used in steps."
+      },
+      "fqn": "projen.github.GitHubActionsProvider",
+      "initializer": {
+        "docs": {
+          "stability": "experimental"
+        }
+      },
+      "kind": "class",
+      "locationInModule": {
+        "filename": "src/github/actions-provider.ts",
+        "line": 4
+      },
+      "methods": [
+        {
+          "docs": {
+            "stability": "experimental",
+            "summary": "Resolve an action name to the version that should be used, taking into account any overrides."
+          },
+          "locationInModule": {
+            "filename": "src/github/actions-provider.ts",
+            "line": 31
+          },
+          "name": "get",
+          "parameters": [
+            {
+              "name": "action",
+              "type": {
+                "primitive": "string"
+              }
+            }
+          ],
+          "returns": {
+            "type": {
+              "primitive": "string"
+            }
+          }
+        },
+        {
+          "docs": {
+            "example": "// Force any use of `actions/checkout` to use a pin a specific commit\nproject.github.actions.set(\"actions/checkout\", \"actions/checkout@aaaaaa\");\n\n// But pin usage of `v3` to a different commit\nproject.github.actions.set(\"actions/checkout@v3\", \"actions/checkout@ffffff\");",
+            "remarks": "Specify the action name without a version to override all usages of the action.\nYou can also override a specific action version, by providing the version string.\nSpecific overrides take precedence over overrides without a version.\n\nIf an override for the same action name is set multiple times, the last override is used.",
+            "stability": "experimental",
+            "summary": "Define an override for a given action."
+          },
+          "locationInModule": {
+            "filename": "src/github/actions-provider.ts",
+            "line": 23
+          },
+          "name": "set",
+          "parameters": [
+            {
+              "name": "action",
+              "type": {
+                "primitive": "string"
+              }
+            },
+            {
+              "name": "override",
+              "type": {
+                "primitive": "string"
+              }
+            }
+          ]
+        }
+      ],
+      "name": "GitHubActionsProvider",
+      "namespace": "github",
+      "symbolId": "src/github/actions-provider:GitHubActionsProvider"
+    },
     "projen.github.GitHubOptions": {
       "assembly": "projen",
       "datatype": true,
@@ -20306,7 +20394,7 @@
       "kind": "interface",
       "locationInModule": {
         "filename": "src/github/github.ts",
-        "line": 10
+        "line": 11
       },
       "name": "GitHubOptions",
       "namespace": "github",
@@ -20321,7 +20409,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/github/github.ts",
-            "line": 16
+            "line": 17
           },
           "name": "mergify",
           "optional": true,
@@ -20339,7 +20427,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/github/github.ts",
-            "line": 23
+            "line": 24
           },
           "name": "mergifyOptions",
           "optional": true,
@@ -20357,7 +20445,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/github/github.ts",
-            "line": 52
+            "line": 53
           },
           "name": "projenCredentials",
           "optional": true,
@@ -20377,7 +20465,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/github/github.ts",
-            "line": 62
+            "line": 63
           },
           "name": "projenTokenSecret",
           "optional": true,
@@ -20395,7 +20483,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/github/github.ts",
-            "line": 38
+            "line": 39
           },
           "name": "pullRequestLint",
           "optional": true,
@@ -20413,7 +20501,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/github/github.ts",
-            "line": 45
+            "line": 46
           },
           "name": "pullRequestLintOptions",
           "optional": true,
@@ -20432,7 +20520,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/github/github.ts",
-            "line": 30
+            "line": 31
           },
           "name": "workflows",
           "optional": true,
@@ -21230,7 +21318,7 @@
         },
         "locationInModule": {
           "filename": "src/github/workflows.ts",
-          "line": 79
+          "line": 81
         },
         "parameters": [
           {
@@ -21257,7 +21345,7 @@
       "kind": "class",
       "locationInModule": {
         "filename": "src/github/workflows.ts",
-        "line": 36
+        "line": 37
       },
       "methods": [
         {
@@ -21267,7 +21355,7 @@
           },
           "locationInModule": {
             "filename": "src/github/workflows.ts",
-            "line": 122
+            "line": 125
           },
           "name": "addJob",
           "parameters": [
@@ -21307,7 +21395,7 @@
           },
           "locationInModule": {
             "filename": "src/github/workflows.ts",
-            "line": 134
+            "line": 137
           },
           "name": "addJobs",
           "parameters": [
@@ -21343,7 +21431,7 @@
           },
           "locationInModule": {
             "filename": "src/github/workflows.ts",
-            "line": 110
+            "line": 113
           },
           "name": "on",
           "parameters": [
@@ -21370,7 +21458,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/github/workflows.ts",
-            "line": 40
+            "line": 41
           },
           "name": "name",
           "type": {
@@ -21385,7 +21473,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/github/workflows.ts",
-            "line": 58
+            "line": 59
           },
           "name": "projenCredentials",
           "type": {
@@ -21401,7 +21489,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/github/workflows.ts",
-            "line": 48
+            "line": 49
           },
           "name": "concurrency",
           "optional": true,
@@ -21418,7 +21506,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/github/workflows.ts",
-            "line": 53
+            "line": 54
           },
           "name": "file",
           "optional": true,
@@ -21434,7 +21522,7 @@
           },
           "locationInModule": {
             "filename": "src/github/workflows.ts",
-            "line": 71
+            "line": 72
           },
           "name": "runName",
           "optional": true,
@@ -21456,7 +21544,7 @@
       "kind": "interface",
       "locationInModule": {
         "filename": "src/github/workflows.ts",
-        "line": 13
+        "line": 14
       },
       "name": "GithubWorkflowOptions",
       "namespace": "github",
@@ -21473,7 +21561,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/github/workflows.ts",
-            "line": 26
+            "line": 27
           },
           "name": "concurrency",
           "optional": true,
@@ -21491,7 +21579,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/github/workflows.ts",
-            "line": 19
+            "line": 20
           },
           "name": "force",
           "optional": true,
@@ -21540,45 +21628,6 @@
       "namespace": "github",
       "symbolId": "src/github/auto-merge:IAddConditionsLater"
     },
-    "projen.github.IJobProvider": {
-      "assembly": "projen",
-      "docs": {
-        "stability": "experimental"
-      },
-      "fqn": "projen.github.IJobProvider",
-      "kind": "interface",
-      "locationInModule": {
-        "filename": "src/github/workflows.ts",
-        "line": 319
-      },
-      "methods": [
-        {
-          "abstract": true,
-          "docs": {
-            "stability": "experimental",
-            "summary": "Generates a collection of named GitHub workflow jobs."
-          },
-          "locationInModule": {
-            "filename": "src/github/workflows.ts",
-            "line": 323
-          },
-          "name": "renderJobs",
-          "returns": {
-            "type": {
-              "collection": {
-                "elementtype": {
-                  "fqn": "projen.github.workflows.Job"
-                },
-                "kind": "map"
-              }
-            }
-          }
-        }
-      ],
-      "name": "IJobProvider",
-      "namespace": "github",
-      "symbolId": "src/github/workflows:IJobProvider"
-    },
     "projen.github.Mergify": {
       "assembly": "projen",
       "base": "projen.Component",
@@ -51783,6 +51832,6 @@
       "symbolId": "src/web/tailwind:TailwindConfigOptions"
     }
   },
-  "version": "0.67.55",
-  "fingerprint": "wdJHP8XIdaSQ42l2X/2nUz8ifzKkr2hLaqRyIq9EbC0="
+  "version": "0.67.56",
+  "fingerprint": "QsG/2umPBk2qG+CY0VWX0YWA2Q4lHTQEYobKrB3BTDQ="
 }

package/docs/api/API.md

@@ -80,6 +80,7 @@ Name|Description
 [github.AutoMerge](#projen-github-automerge)|Sets up mergify to merging approved pull requests.
 [github.Dependabot](#projen-github-dependabot)|Defines dependabot configuration for node projects.
 [github.GitHub](#projen-github-github)|*No description*
+[github.GitHubActionsProvider](#projen-github-githubactionsprovider)|Manage the versions used for GitHub Actions used in steps.
 [github.GitHubProject](#projen-github-githubproject)|GitHub-based project.
 [github.GithubCredentials](#projen-github-githubcredentials)|Represents a method of providing GitHub API access for projen workflows.
 [github.GithubWorkflow](#projen-github-githubworkflow)|Workflow for GitHub.
@@ -411,7 +412,6 @@ Name|Description
 [IResolvable](#projen-iresolvable)|*No description*
 [IResolver](#projen-iresolver)|API for resolving tokens when synthesizing file content.
 [github.IAddConditionsLater](#projen-github-iaddconditionslater)|*No description*
-[github.IJobProvider](#projen-github-ijobprovider)|*No description*
 [python.IPackageProvider](#projen-python-ipackageprovider)|*No description*
 [python.IPythonDeps](#projen-python-ipythondeps)|*No description*
 [python.IPythonEnv](#projen-python-ipythonenv)|*No description*
@@ -6555,6 +6555,7 @@ new github.GitHub(project: Project, options?: GitHubOptions)
 
 Name | Type | Description 
 -----|------|-------------
+**actions**🔹 | <code>[github.GitHubActionsProvider](#projen-github-githubactionsprovider)</code> | <span></span>
 **projenCredentials**🔹 | <code>[github.GithubCredentials](#projen-github-githubcredentials)</code> | GitHub API authentication method used by projen workflows.
 **workflows**🔹 | <code>Array<[github.GithubWorkflow](#projen-github-githubworkflow)></code> | All workflows.
 **workflowsEnabled**🔹 | <code>boolean</code> | Are workflows enabled?
@@ -6638,6 +6639,62 @@ __Returns__:
 
 
 
+## class GitHubActionsProvider 🔹 <a id="projen-github-githubactionsprovider"></a>
+
+Manage the versions used for GitHub Actions used in steps.
+
+__Submodule__: github
+
+
+### Initializer
+
+
+
+
+```ts
+new github.GitHubActionsProvider()
+```
+
+
+
+### Methods
+
+
+#### get(action)🔹 <a id="projen-github-githubactionsprovider-get"></a>
+
+Resolve an action name to the version that should be used, taking into account any overrides.
+
+```ts
+get(action: string): string
+```
+
+* **action** (<code>string</code>)  *No description*
+
+__Returns__:
+* <code>string</code>
+
+#### set(action, override)🔹 <a id="projen-github-githubactionsprovider-set"></a>
+
+Define an override for a given action.
+
+Specify the action name without a version to override all usages of the action.
+You can also override a specific action version, by providing the version string.
+Specific overrides take precedence over overrides without a version.
+
+If an override for the same action name is set multiple times, the last override is used.
+
+```ts
+set(action: string, override: string): void
+```
+
+* **action** (<code>string</code>)  *No description*
+* **override** (<code>string</code>)  *No description*
+
+
+
+
+
+
 ## class GitHubProject ⚠️ <a id="projen-github-githubproject"></a>
 
 GitHub-based project.
@@ -15504,27 +15561,6 @@ __Returns__:
 
 
 
-## interface IJobProvider 🔹 <a id="projen-github-ijobprovider"></a>
-
-
-
-### Methods
-
-
-#### renderJobs()🔹 <a id="projen-github-ijobprovider-renderjobs"></a>
-
-Generates a collection of named GitHub workflow jobs.
-
-```ts
-renderJobs(): Map<string, Job>
-```
-
-
-__Returns__:
-* <code>Map<string, [github.workflows.Job](#projen-github-workflows-job)></code>
-
-
-
 ## struct MergifyConditionalOperator 🔹 <a id="projen-github-mergifyconditionaloperator"></a>
 
 

package/docs/github.md

@@ -1,6 +1,6 @@
 # GitHub
 
-By default, many projects are initialized with `GitHub` component to enabled GitHub as the default provider for CI/CD workflows. See https://docs.github.com/en/actions for more information.
+By default, many projects are initialized with `GitHub` component to enabled GitHub as the default provider for CI/CD workflows. See <https://docs.github.com/en/actions> for more information.
 
 The use of GitHub (and generating corresponding files in `.github`) can be disabled by specifying `github: false` in your project options.
 
@@ -80,14 +80,54 @@ const project = new javascript.NodeProject({
 
 ## Workflows
 
-TODO
-
 See the `GitHub`, `GithubWorkflow`, and `Job` types in the [API
 reference](./api/API.md) for currently available APIs.
 
 Example code of creating a GitHub workflow:
 <https://github.com/projen/projen/blob/65b4194c163f47ba4842981b0c92dbe516be787b/src/github/auto-approve.ts#L67-L105>
 
+### Actions versions
+
+Most workflows included with projen are constraint to a major version, in order for updates to be available immediately.
+However it is a good security practice to lock versions of GitHub Actions down to explicit commit hashes.
+To achieve this, you can define explicit overrides for any action used in workflows.
+
+The replace all occurrences of an action can be overridden, irregardless of the action version:
+
+```ts
+project.github.actions.set("actions/checkout", "actions/checkout@ac59398");
+```
+
+Any use of `actions/checkout` is now changed to this:
+
+```yaml
+steps:
+  - uses: actions/checkout@ac59398
+```
+
+Alternatively, any specific action version can be overridden.
+This can be useful when a specific version of an action must be used due to incompatible changes.
+Specific overrides take precedence over overrides without a version.
+
+```ts
+project.github.actions.set("actions/checkout@v3", "actions/checkout@ac59398");
+project.github.actions.set("actions/checkout", "actions/checkout@main");
+```
+
+Different versions of `actions/checkout` are resolved to different overrides:
+
+```yaml
+steps:
+  # Was: actions/checkout@v3
+  - uses: actions/checkout@ac59398
+
+  # Was: actions/checkout@v2
+  - uses: actions/checkout@main
+```
+
+Workflow creators are encouraged to use commit hashes and keep them updated, or major versions.
+Sensitive workflow actions should always use commit hashes.
+
 ### Stale workflow
 
 A "stale" workflow can be added which will automatically close issues or pull