docs: API tokens & CI automation (#4510)

* reword: chore: add CI to dogfood template

* use hardcoded URL

* use consistent name for tokens

* chore: add docs for template change management

* add an example

* fix case

.github/workflows/dogfood.yaml

@@ -12,7 +12,7 @@ on:
   workflow_dispatch:
 
 jobs:
-  deploy:
+  deploy_image:
     runs-on: ubuntu-latest
     steps:
       - name: Get branch name
@@ -47,3 +47,27 @@ jobs:
           tags: "codercom/oss-dogfood:${{ steps.docker-tag-name.outputs.tag }},codercom/oss-dogfood:latest"
           cache-from: type=registry,ref=codercom/oss-dogfood:latest
           cache-to: type=inline
+  deploy_template:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+      - name: Get short commit SHA
+        id: vars
+        run: echo "::set-output name=sha_short::$(git rev-parse --short HEAD)"
+      - name: "Install latest Coder"
+        run: |
+          curl -L https://coder.com/install.sh | sh
+        # env:
+        #   VERSION: 0.x
+      - name: "Push template"
+        run: |
+          coder templates push $CODER_TEMPLATE_NAME --directory $CODER_TEMPLATE_DIR --yes --name=$CODER_TEMPLATE_VERSION
+        env:
+          # Consumed by Coder CLI
+          CODER_URL: https://dev.coder.com
+          CODER_SESSION_TOKEN: ${{ secrets.CODER_SESSION_TOKEN }}
+          # Template source & details
+          CODER_TEMPLATE_NAME: ${{ secrets.CODER_TEMPLATE_NAME }}
+          CODER_TEMPLATE_VERSION: ${{ steps.vars.outputs.sha_short }}
+          CODER_TEMPLATE_DIR: ./dogfood

cli/tokens.go

@@ -67,7 +67,7 @@ func createToken() *cobra.Command {
 			cmd.Println(cliui.Styles.Code.Render(strings.TrimSpace(res.Key)))
 			cmd.Println()
 			cmd.Println(cliui.Styles.Wrap.Render(
-				fmt.Sprintf("You can use this token by setting the --%s CLI flag, the %s environment variable, or the %q HTTP header.", varToken, envSessionToken, codersdk.SessionTokenKey),
+				fmt.Sprintf("You can use this token by setting the --%s CLI flag, the %s environment variable, or the %q HTTP header.", varToken, envSessionToken, codersdk.SessionCustomHeader),
 			))
 
 			return nil

docs/admin/automation.md

@@ -0,0 +1,37 @@
+# Automation
+
+We recommend automating Coder deployments through the CLI. Examples include [updating templates via CI/CD pipelines](../templates/change-management.md).
+
+## Tokens
+
+Long-lived tokens can be generated to perform actions on behalf of your user account:
+
+```sh
+coder tokens create
+```
+
+## CLI
+
+You can use tokens with the CLI by setting the `--token` CLI flag or the `CODER_SESSION_TOKEN`
+environment variable.
+
+```sh
+export CODER_URL=https://coder.example.com
+export CODER_SESSION_TOKEN=*****
+coder workspaces ls
+```
+
+## REST API
+
+You can use tokens with the Coder's REST API using the `Coder-Session-Token` HTTP header.
+
+```sh
+curl 'https://dev.coder.com/api/v2/workspaces' \
+  -H 'Coder-Session-Token: *****'
+```
+
+> At this time, we do not publish an API reference. However, [codersdk](https://github.com/coder/coder/tree/main/codersdk) can be grepped to find the necessary routes and payloads.
+
+## Golang SDK
+
+Coder publishes a public [Golang SDK](https://pkg.go.dev/github.com/coder/coder@main/codersdk) for Coder. This is consumed by the [CLI package](https://github.com/coder/coder/tree/main/cli).

docs/images/icons/git.svg

@@ -0,0 +1,4 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 114 114">
+  <path fill="#100f0d" d="m112.693375 52.3185-50.149-50.146875c-2.886625-2.88875-7.57075-2.88875-10.461375 0l-10.412625 10.4145 13.2095 13.2095C57.94975 24.759 61.47025 25.45475 63.9165 27.9015c2.461 2.462 3.150875 6.01275 2.087375 9.09375l12.732 12.7305c3.081-1.062 6.63325-.3755 9.09425 2.088875 3.4375 3.4365 3.4375 9.007375 0 12.44675-3.44 3.4395-9.00975 3.4395-12.45125 0-2.585375-2.587875-3.225125-6.387125-1.914-9.57275l-11.875-11.874V74.06075c.837375.415 1.628375.96775 2.326625 1.664 3.4375 3.437125 3.4375 9.007375 0 12.44975-3.4375 3.436-9.01125 3.436-12.44625 0-3.4375-3.442375-3.4375-9.012625 0-12.44975.849625-.848625 1.8335-1.490625 2.88325-1.920375V42.26925c-1.04975-.42975-2.03125-1.066375-2.88325-1.920875-2.6035-2.602625-3.23-6.424375-1.894625-9.622125L36.55325 17.701875 2.1660125 52.086125c-2.88818 2.891125-2.88818 7.57525 0 10.463875l50.1513625 50.146975c2.88725 2.88818125 7.569875 2.88818125 10.461375 0l49.914625-49.9146c2.889625-2.889125 2.889625-7.575625 0-10.463875"/>
+</svg>

docs/images/icons/plug.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" enable-background="new 0 0 24 24" height="24" viewBox="0 0 24 24" width="24"><g><rect fill="none" height="24" width="24"/></g><g><g><path d="M21,14c0-0.55-0.45-1-1-1h-2v2h2C20.55,15,21,14.55,21,14z"/><path d="M20,17h-2v2h2c0.55,0,1-0.45,1-1C21,17.45,20.55,17,20,17z"/><path d="M12,14h-2v4h2c0,1.1,0.9,2,2,2h3v-8h-3C12.9,12,12,12.9,12,14z"/><path d="M5,13c0-1.1,0.9-2,2-2h1.5c1.93,0,3.5-1.57,3.5-3.5S10.43,4,8.5,4H5C4.45,4,4,4.45,4,5c0,0.55,0.45,1,1,1h3.5 C9.33,6,10,6.67,10,7.5S9.33,9,8.5,9H7c-2.21,0-4,1.79-4,4c0,2.21,1.79,4,4,4h2v-2H7C5.9,15,5,14.1,5,13z"/></g></g></svg>

docs/manifest.json

@@ -95,6 +95,12 @@
           "path": "./templates/authentication.md",
           "icon_path": "./images/icons/key.svg"
         },
+        {
+          "title": "Change Management",
+          "description": "Learn how to source-control templates with git and CI",
+          "path": "./templates/change-management.md",
+          "icon_path": "./images/icons/git.svg"
+        },
         {
           "title": "Resource Metadata",
           "description": "Learn how to expose resource data to users",
@@ -212,6 +218,12 @@
           "icon_path": "./images/icons/upgrade.svg",
           "path": "./admin/upgrade.md"
         },
+        {
+          "title": "Automation",
+          "description": "Learn how to automate Coder with the CLI and API",
+          "icon_path": "./images/icons/plug.svg",
+          "path": "./admin/automation.md"
+        },
         {
           "title": "Audit Logs",
           "description": "Learn how to use Audit Logs in your Coder deployment.",

docs/templates.md

@@ -314,14 +314,9 @@ practices:
 
 Template permissions can be used to give users and groups access to specific templates. [Learn more about RBAC](./admin/rbac.md).
 
-## Change Management
-
-We recommend source controlling your templates as you would other code.
-
-CI is as simple as running `coder templates push` with the appropriate
-credentials.
-
 ## Next Steps
 
 - Learn about [Authentication & Secrets](templates/authentication.md)
+- Learn about [Change Management](templates/change-management.md)
+- Learn about [Resource Metadata](templates/resource-metadata.md)
 - Learn about [Workspaces](workspaces.md)

docs/templates/change-management.md

@@ -0,0 +1,23 @@
+# Template Change Management
+
+We recommend source controlling your templates as you would other code. [Install Coder](../install/) in CI/CD pipelines to push new template versions.
+
+```sh
+# Install the Coder CLI
+curl -L https://coder.com/install.sh | sh
+# curl -L https://coder.com/install.sh | sh -s -- --version=0.x
+
+# To create API tokens, use `coder tokens create`.
+# These variables are consumed by Coder
+export CODER_URL=https://coder.example.com
+export CODER_SESSION_TOKEN=*****
+
+# Template details
+export CODER_TEMPLATE_NAME=kubernetes
+export CODER_TEMPLATE_DIR=.coder/templates/kubernetes
+export CODER_TEMPLATE_VERSION=$(git rev-parse --short HEAD)
+
+coder templates push --yes $CODER_TEMPLATE_NAME \
+    --directory $CODER_TEMPLATE_DIR \
+    --name=$CODER_TEMPLATE_VERSION # Version name is optional
+```