+ 
+
+ 
+ 
+
+
Get started with the javascript-action template!
++ +## Packages + +:heavy_check_mark: [@actions/core](packages/core) + +Provides functions for inputs, outputs, results, logging, secrets and variables. Read more [here](packages/core) + +```bash +$ npm install @actions/core +``` +
+ +:runner: [@actions/exec](packages/exec) + +Provides functions to exec cli tools and process output. Read more [here](packages/exec) + +```bash +$ npm install @actions/exec +``` +
+ +:ice_cream: [@actions/glob](packages/glob) + +Provides functions to search for files matching glob patterns. Read more [here](packages/glob) + +```bash +$ npm install @actions/glob +``` +
+ +:phone: [@actions/http-client](packages/http-client) + +A lightweight HTTP client optimized for building actions. Read more [here](packages/http-client) + +```bash +$ npm install @actions/http-client +``` +
+ +:pencil2: [@actions/io](packages/io) + +Provides disk i/o functions like cp, mv, rmRF, which etc. Read more [here](packages/io) + +```bash +$ npm install @actions/io +``` +
+ +:hammer: [@actions/tool-cache](packages/tool-cache) + +Provides functions for downloading and caching tools. e.g. setup-* actions. Read more [here](packages/tool-cache) + +See @actions/cache for caching workflow dependencies. + +```bash +$ npm install @actions/tool-cache +``` +
+ +:octocat: [@actions/github](packages/github) + +Provides an Octokit client hydrated with the context that the current action is being run in. Read more [here](packages/github) + +```bash +$ npm install @actions/github +``` +
+ +:floppy_disk: [@actions/artifact](packages/artifact) + +Provides functions to interact with actions artifacts. Read more [here](packages/artifact) + +```bash +$ npm install @actions/artifact +``` +
+ +:dart: [@actions/cache](packages/cache) + +Provides functions to cache dependencies and build outputs to improve workflow execution time. Read more [here](packages/cache) + +```bash +$ npm install @actions/cache +``` +
+ +## Creating an Action with the Toolkit + +:question: [Choosing an action type](docs/action-types.md) + +Outlines the differences and why you would want to create a JavaScript or a container based action. +
+
+ +:curly_loop: [Versioning](docs/action-versioning.md) + +Actions are downloaded and run from the GitHub graph of repos. This contains guidance for versioning actions and safe releases. +
+
+ +:warning: [Problem Matchers](docs/problem-matchers.md) + +Problem Matchers are a way to scan the output of actions for a specified regex pattern and surface that information prominently in the UI. +
+
+ +:warning: [Proxy Server Support](docs/proxy-support.md) + +Self-hosted runners can be configured to run behind proxy servers. +
+
+ +
Hello World JavaScript Action
+ +Illustrates how to create a simple hello world javascript action. + +```javascript +... + const nameToGreet = core.getInput('who-to-greet'); + console.log(`Hello ${nameToGreet}!`); +... +``` ++ +
JavaScript Action Walkthrough
+ +Walkthrough and template for creating a JavaScript Action with tests, linting, workflow, publishing, and versioning. + +```javascript +async function run() { + try { + const ms = core.getInput('milliseconds'); + console.log(`Waiting ${ms} milliseconds ...`) + ... +``` +```javascript +PASS ./index.test.js + ✓ throws invalid number + ✓ wait 500 ms + ✓ test runs + +Test Suites: 1 passed, 1 total +Tests: 3 passed, 3 total +``` ++ +
TypeScript Action Walkthrough
+ +Walkthrough creating a TypeScript Action with compilation, tests, linting, workflow, publishing, and versioning. + +```javascript +import * as core from '@actions/core'; + +async function run() { + try { + const ms = core.getInput('milliseconds'); + console.log(`Waiting ${ms} milliseconds ...`) + ... +``` +```javascript +PASS ./index.test.js + ✓ throws invalid number + ✓ wait 500 ms + ✓ test runs + +Test Suites: 1 passed, 1 total +Tests: 3 passed, 3 total +``` ++
+ +
Docker Action Walkthrough
+ +Create an action that is delivered as a container and run with docker. + +```docker +FROM alpine:3.10 +COPY LICENSE README.md / +COPY entrypoint.sh /entrypoint.sh +ENTRYPOINT ["/entrypoint.sh"] +``` ++ +
Docker Action Walkthrough with Octokit
+ +Create an action that is delivered as a container which uses the toolkit. This example uses the GitHub context to construct an Octokit client. + +```docker +FROM node:slim +COPY . . +RUN npm install --production +ENTRYPOINT ["node", "/lib/main.js"] +``` +```javascript +const myInput = core.getInput('myInput'); +core.debug(`Hello ${myInput} from inside a container`); + +const context = github.context; +console.log(`We can even get context data, like the repo: ${context.repo.repo}`) +``` ++ +## Contributing + +We welcome contributions. See [how to contribute](.github/CONTRIBUTING.md). + +## Code of Conduct + +See [our code of conduct](CODE_OF_CONDUCT.md). diff --git a/actions-toolkit/SECURITY.md b/actions-toolkit/SECURITY.md new file mode 100644 index 00000000..fc3f6d19 --- /dev/null +++ b/actions-toolkit/SECURITY.md @@ -0,0 +1,3 @@ +If you discover a security issue in this repo, please submit it through the [GitHub Security Bug Bounty](https://hackerone.com/github) + +Thanks for helping make GitHub Actions safe for everyone. \ No newline at end of file diff --git a/actions-toolkit/docs/action-debugging.md b/actions-toolkit/docs/action-debugging.md new file mode 100644 index 00000000..d5834693 --- /dev/null +++ b/actions-toolkit/docs/action-debugging.md @@ -0,0 +1,31 @@ +# Debugging +If the job logs do not provide enough detail on why a job may be failing, some other options exist to assist with troubleshooting. + +## Step Debug Logs +This is the primary way for customers to debug job failures caused by failed steps. + +Step debug logs increase the verbosity of a job's logs during and after a job's execution to assist with troubleshooting. + +Additional log events with the prefix `::debug::` will now also appear in the job's logs, these log events are provided by the Action's author and the runner process. + +### How to Access Step Debug Logs +This flag can be enabled by [setting the secret](https://help.github.com/en/actions/automating-your-workflow-with-github-actions/creating-and-using-encrypted-secrets#creating-encrypted-secrets) `ACTIONS_STEP_DEBUG` to `true`. + +All actions ran while this secret is enabled will show debug events in the [Downloaded Logs](https://help.github.com/en/actions/automating-your-workflow-with-github-actions/managing-a-workflow-run#downloading-logs) and [Web Logs](https://help.github.com/en/actions/automating-your-workflow-with-github-actions/managing-a-workflow-run#viewing-logs-to-diagnose-failures). + +## Runner Diagnostic Logs +Runner Diagnostic Logs provide additional log files detailing how the Runner is executing an action. + +You need the runner diagnostic logs only if you think there is an infrastructure problem with GitHub Actions and you want the product team to check the logs. + +Each file contains different logging information that corresponds to that process: + * The Runner process coordinates setting up workers to execute jobs. + * The Worker process executes the job. + +These files contain the prefix `Runner_` or `Worker_` to indicate the log source. + +### How to Access Runner Diagnostic Logs +These log files are enabled by [setting the secret](https://help.github.com/en/actions/automating-your-workflow-with-github-actions/creating-and-using-encrypted-secrets#creating-encrypted-secrets) `ACTIONS_RUNNER_DEBUG` to `true`. + +All actions ran while this secret is enabled contain additional diagnostic log files in the `runner-diagnostic-logs` folder of the [log archive](https://help.github.com/en/actions/automating-your-workflow-with-github-actions/managing-a-workflow-run#downloading-logs). + diff --git a/actions-toolkit/docs/action-types.md b/actions-toolkit/docs/action-types.md new file mode 100644 index 00000000..299ce76a --- /dev/null +++ b/actions-toolkit/docs/action-types.md @@ -0,0 +1,45 @@ +# Action Types + +There are two types of actions. JavaScript and Docker actions. + +- **JavaScript Actions**: JavaScript actions run on the host machine. The unit of work is decoupled from the environment. +- **Docker Actions**: A container action is a container which carries both the unit of work along with the environment and its dependencies packaged up as a container. + +Both have access to the workspace and the github event payload and context. + +## Why would I choose a Docker action? + +Docker actions carry both the unit of work and the environment. + +This creates a more consistent and reliable unit of work where the consumer of the action does not need to worry about the toolsets and its dependencies. + +Docker actions are currently limited to Linux only. + +## Why would I choose a host action? + +JavaScript actions decouple the unit of work from the environment and run directly on the host machine or VM. + +Consider a simple example of testing a node lib on node 8, 10 and running a custom action. Each job will setup a node version on the host and custom-action will run its unit of work on each environment (node8+ubuntu16, node8+windows-2019, etc.) + +```yaml +on: push + +jobs: + build: + strategy: + matrix: + node: [8.x, 10.x] + os: [ubuntu-16.04, windows-2019] + runs-on: ${{matrix.os}} + actions: + - uses: actions/setup-node@v3 + with: + version: ${{matrix.node}} + - run: | + npm install + - run: | + npm test + - uses: actions/custom-action@v1 +``` + +JavaScript actions work on any environment that host action runtime is supported on which is currently node 12. However, a host action that runs a toolset expects the environment that it's running on to have that toolset in its PATH or using a setup-* action to acquire it on demand. diff --git a/actions-toolkit/docs/action-versioning.md b/actions-toolkit/docs/action-versioning.md new file mode 100644 index 00000000..b1847424 --- /dev/null +++ b/actions-toolkit/docs/action-versioning.md @@ -0,0 +1,63 @@ +# Versioning + +Actions are downloaded and run from the GitHub graph of repos. The workflow references an action using a ref. + +Examples: + +```yaml +steps: + - uses: actions/javascript-action@v1 # recommended. starter workflows use this + - uses: actions/javascript-action@v1.0.0 # if an action offers specific releases + - uses: actions/javascript-action@41775a4da8ffae865553a738ab8ac1cd5a3c0044 # sha +``` + +# Compatibility + +Binding to a major version is the latest of that major version ( e.g. `v1` == "1.*" ) + +Major versions should guarantee compatibility. A major version can add net new capabilities but should not break existing input compatibility or break existing workflows. + +Major version binding allows you to take advantage of bug fixes and critical functionality and security fixes. The `main` branch has the latest code and is unstable to bind to since changes get committed to main and released to the market place by creating a tag. In addition, a new major version carrying breaking changes will get implemented in main after branching off the previous major version. + +> Warning: do not reference `main` since that is the latest code and can be carrying breaking changes of the next major version. + +```yaml +steps: + - uses: actions/javascript-action@main # do not do this +``` + +Binding to the immutable full sha1 may offer more reliability. However, note that the hosted images toolsets (e.g. ubuntu-latest) move forward and if there is a tool breaking issue, actions may react with a patch to a major version to compensate so binding to a specific SHA may prevent you from getting fixes. + +> Recommendation: bind to major versions to get functionality and fixes but reserve binding to a specific release or SHA as a mitigation strategy for unforeseen breaks. + +# Recommendations + +1. **Create a GitHub release for each specific version**: Creating a release like [ v1.0.0 ](https://github.com/actions/javascript-action/releases/tag/v1.0.0) allows users to bind back to a specific version if an issue is encountered with the latest major version. + +2. **Publish the specific version to the marketplace**: When you release a specific version, choose the option to "Publish this Action to the GitHub Marketplace". + +
+
+3. **Make the new release available to those binding to the major version tag**: Move the major version tag (v1, v2, etc.) to point to the ref of the current release. This will act as the stable release for that major version. You should keep this tag updated to the most recent stable minor/patch release.
+
+```
+git tag -fa v1 -m "Update v1 tag"
+git push origin v1 --force
+```
+# Major Versions
+
+All releases for a major version should hold compat including input compatibility and behavior compatibility.
+
+Introduce a major version for compatibility breaks and major rewrites of the action.
+
+Ideally, a major version would carry other benefits to the user to entice them to upgrade their workflows. Since updating their workflows will need to be done with an understanding of the changes and what compatibility was broken, introducing a new major version shouldn't be taken lightly.
+
+To get feedback and to set expectations, the new major version can be initially released with `v2-beta` tag to indicate you can try it out but it's still going under some churn. Upon release the `-beta` can be dropped and there's an expectation of compatibility from that point forward.
+
+[An example of v2-beta with checkout](https://github.com/actions/checkout/tree/c170eefc2657d93cc91397be50a299bff978a052#checkout-v2-beta)
+
+# Sample Workflow
+
+This illustrates the versioning workflow covered above.
+
+
diff --git a/actions-toolkit/docs/adrs/0381-glob-module.md b/actions-toolkit/docs/adrs/0381-glob-module.md
new file mode 100644
index 00000000..a61fd8bb
--- /dev/null
+++ b/actions-toolkit/docs/adrs/0381-glob-module.md
@@ -0,0 +1,216 @@
+# ADR 381: `glob` module
+
+**Date**: 2019-12-05
+
+**Status**: Accepted
+
+## Context
+
+This ADR proposes adding a `glob` function to the toolkit.
+
+First party actions should have a consistent glob experience.
+
+Related to artifact upload/download v2.
+
+## Decision
+
+### New module
+
+Create a new module `@actions/glob` that can be versioned at it's own pace - not tied to `@actions/io`.
+
+### Signature
+
+```js
+/**
+ * Constructs a globber from patterns
+ *
+ * @param patterns Patterns separated by newlines
+ * @param options Glob options
+ */
+export function create(
+ patterns: string,
+ options?: GlobOptions
+): Promise