initial gh action docs

packages/docs-site/astro.config.ts

@@ -214,6 +214,10 @@ export default defineConfig({
               label: 'Vercel',
               link: '/docs/platforms/vercel/',
             },
+            {
+              label: 'GitHub Actions',
+              link: '/docs/platforms/github-actions/',
+            },
           ],
         }, {
           label: 'Reference',

packages/docs-site/src/content/docs/docs/platforms/github-actions.mdx

@@ -0,0 +1,236 @@
+---
+title: Using DMNO with GitHub Actions
+description: Use DMNO's GitHub Action to reuse your env vars across your GitHub Actions workflows
+---
+
+import BugReportLink from '@/components/BugReportLink.astro';
+
+While DMNO provides everything you need to manage your env vars in your repo, you may want to reuse your env vars across your GitHub Actions workflows. We created a [GitHub Action](https://github.com/marketplace/actions/dmno-secrets-and-config) that makes this easier.
+
+:::tip
+If you only need to use DMNO, and associated env vars, in a single workflow step then you probably don't need this action.
+:::
+
+## Getting Started Workflow
+
+```yaml title='.github/workflows/my-workflow.yml'
+name: My Workflow
+
+on:
+  # replace with your own trigger(s)
+  push:
+    branches:
+      - main
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      # Checkout your repo 
+      - uses: actions/checkout@v4
+      # setup Node.js
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+      # Install dependencies
+      - name: Install dependencies
+        run: npm install
+      # Run DMNO to get your env vars
+      - uses: dmno/dmno-gh-action@v1
+        id: dmnoStep
+        with:
+          service-name: 'my-dmno-service'
+      - id: nextStep
+        run: |
+          # Use the env var in your workflow
+          echo $MY_ENV_VAR
+
+```
+
+## Configuration
+
+### Inputs
+
+- `service-name`: Explicitly select the service to populate config for (useful
+  in a monorepo with multiple services)
+- `base-directory`: The base directory to generate config for, if not provided,
+  the current working directory will be used
+- `phase`: The phase of the service to generate config for
+- `emit-env-vars`: Whether to emit environment variables, defaults to true
+- `output-vars`: Whether to also provide the variables in the output, defaults
+  to false
+- `skip-regex`: The regular expression to skip config for, defaults to empty
+  string
+- `skip-cache`: Whether to skip the cache, defaults to false
+- `clear-cache`: Whether to clear the cache, defaults to false
+
+### Outputs
+
+If `emit-env-vars` is `true`, each of your config variables will be emitted as
+an environment variable.
+
+If `output-vars` is `true`, `DMNO_CONFIG` is output as a JSON string of
+key-value pairs of the generated variables after being processed by the
+`skip-regex` regular expression.
+
+## Additional Workflow Examples
+
+We'll use the following DMNO service as an example for all of the following workflows:
+
+```typescript title='.dmno/config.mts'
+import { defineDmnoService } from 'dmno';
+import { OnePasswordDmnoPlugin, OnePasswordTypes } from '@dmno/1password-plugin';
+
+// token will be injected using types by default
+const onePassSecrets = new OnePasswordDmnoPlugin('1pass');
+
+export default defineDmnoService({
+  name: 'my-dmno-service',
+  schema: {
+    MY_ENV_VAR: {
+      value: 'some-value',
+    },
+    OP_TOKEN: {
+      extends: OnePasswordTypes.serviceAccountToken,
+    },
+    ITEM_FROM_1PASS: {
+      value: onePassSecrets.itemByReference('op://vaultname/itemname/path'),
+    },
+  }
+});
+```
+
+### Using the config in a multi-step jobs
+
+This is a common example where you can re-use the environment variables in a subsequent step in the same job. By default, each item in your schema will be emitted as an environment variable.
+
+You can use the config in a multi-step job like this:
+
+```yaml title='.github/workflows/my-multi-step-job.yml'
+name: My Multi-Step Job Workflow
+
+on:
+  # replace with your own trigger(s)
+  push:
+    branches:
+      - main
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      # Checkout your repo 
+      - uses: actions/checkout@v4
+      # setup Node.js
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+      # Install dependencies
+      - name: Install dependencies
+        run: npm install
+      # Run the DMNO action to get your env vars
+      - uses: dmno/dmno-gh-action@v1
+        id: dmnoStep
+        with:
+          service-name: 'my-dmno-service'
+      # Use the env var in the next step
+      - id: lastStep
+        run: |
+          echo $MY_ENV_VAR
+```
+
+### Using the config in a multi-job workflow
+
+Multi-job workflows are slightly more complex since each job will have its own set of environment variables. This means you will need to explicity set the outputs you need to use in any other jobs via the `needs` block. 
+
+```yaml title='.github/workflows/my-multi-job-workflow.yml'
+name: My Multi-Job Workflow
+
+on:
+  # replace with your own trigger(s)
+  push:
+    branches:
+      - main
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    outputs:
+      # the single env var we want to use
+      MY_ENV_VAR: ${{ steps.lastStep.outputs.MY_ENV_VAR }}
+      # full stringified JSON of all env vars
+      DMNO_CONFIG: ${{ steps.dmnoStep.outputs.DMNO_CONFIG }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+      - name: Install dependencies
+        run: npm install
+      - uses: dmno/dmno-gh-action@v1
+        id: dmnoStep
+        with:
+          service-name: 'my-dmno-service'
+          output-vars: true
+      - id: lastStep
+        run: |
+          echo "MY_ENV_VAR=$MY_ENV_VAR" >> "$GITHUB_OUTPUT"
+  after_build:
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - run: echo {{ needs.build.outputs.MY_ENV_VAR }}
+      - run: echo {{ needs.build.outputs.DMNO_CONFIG }}
+```
+
+### Using with a DMNO plugin (1Password)
+
+If you're using a plugin that requires a sensitive input, you can set the input as a secret in GitHub and then pass it to the action as an environment variable with the `env` block. In most cases, this means you will only need to set a single secret via GitHub and let DMNO handle loading the rest. 
+
+In this example, we're using the [1Password plugin](/docs/plugins/overview/) but the workflow is similar for any plugin that requires a sensitive input.
+
+```yaml title='.github/workflows/my-1password-workflow.yml'
+name: My 1Password Workflow
+
+on:
+  # replace with your own trigger(s)
+  push:
+    branches:
+      - main
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+      - name: Install dependencies
+        run: npm install
+      - uses: dmno/dmno-gh-action@v1
+        id: dmnoWith1Password
+        env:
+          # 1Password service account token, set as a secret in GitHub
+          OP_TOKEN: ${{ secrets.OP_TOKEN }}
+        with:
+          service-name: 'my-dmno-service'
+      - id: nextStep
+        run: |
+          # Use the item from 1Password in your workflow
+          echo $ITEM_FROM_1PASS
+```
+
+
+
+## Troubleshooting
+
+Make sure: 
+
+- DMNO is installed and [set up](/docs/get-started/quickstart/) in your repo
+- You have a `.dmno/config.mts` with a [valid schema](/docs/guides/schema/)
+- Your action checks out the repo (e.g., `actions/checkout@v4`)
+- Your action installs dependencies (e.g., `npm install`)
+- You have set any required sensitive [plugin](/docs/plugins/overview/) inputs (e.g., Your 1Password service account token) as [secrets](https://docs.github.com/en/actions/security-for-github-actions/security-guides/using-secrets-in-github-actions) for your repo or as [environment variables](https://docs.github.com/en/actions/security-for-github-actions/security-guides/security-for-github-actions#using-environment-variables-in-your-workflow) in your repo. (See example above.)
+
+:::note
+If you run into any issues, feel free to <BugReportLink label='integrations/astro'>report them to us on GitHub</BugReportLink> and try the manual installation steps below.
+:::