diff --git a/docs/plugins.rst b/docs/plugins.rst
index 3b3653cc..0b4dcced 100644
--- a/docs/plugins.rst
+++ b/docs/plugins.rst
@@ -219,6 +219,8 @@ Here is an example of some plugin configuration for a specific table::
 
 This tells the ``datasette-cluster-map`` column which latitude and longitude columns should be used for a table called ``Street_Tree_List`` inside a database file called ``sf-trees.db``.
 
+.. _plugins_configuration_secret:
+
 Secret configuration values
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -236,7 +238,6 @@ Any values embedded in ``metadata.json`` will be visible to anyone who views the
         }
     }
 
-
 **As values in separate files**. Your secrets can also live in files on disk. To specify a secret should be read from a file, provide the full file path like this::
 
     {
@@ -249,6 +250,14 @@ Any values embedded in ``metadata.json`` will be visible to anyone who views the
         }
     }
 
+If you are publishing your data using the :ref:`datasette publish <cli_publish>` family of commands, you can use the ``--plugin-secret`` option to set these secrets at publish time. For example, using Heroku you might run the following command::
+
+    $ datasette publish heroku my_database.db \
+        --name my-heroku-app-demo \
+        --install=datasette-auth-github \
+        --plugin-secret datasette-auth-github client_id your_client_id \
+        --plugin-secret datasette-auth-github client_secret your_client_secret
+
 Writing plugins that accept configuration
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
diff --git a/docs/publish.rst b/docs/publish.rst
index c9039734..009ae199 100644
--- a/docs/publish.rst
+++ b/docs/publish.rst
@@ -6,6 +6,8 @@
 
 Datasette includes tools for publishing and deploying your data to the internet. The ``datasette publish`` command will deploy a new Datasette instance containing your databases directly to a Heroku, Google Cloud or Zeit Now hosting account. You can also use ``datasette package`` to create a Docker image that bundles your databases together with the datasette application that is used to serve them.
 
+.. _cli_publish:
+
 datasette publish
 =================
 
@@ -99,6 +101,13 @@ You can also specify plugins you would like to install. For example, if you want
 
     datasette publish nowv1 mydatabase.db --install=datasette-vega
 
+If a plugin has any :ref:`plugins_configuration_secret` you can use the ``--plugin-secret`` option to set those secrets at publish time. For example, using Heroku with `datasette-auth-github <https://github.com/simonw/datasette-auth-github>`__ you might run the following command::
+
+    $ datasette publish heroku my_database.db \
+        --name my-heroku-app-demo \
+        --install=datasette-auth-github \
+        --plugin-secret datasette-auth-github client_id your_client_id \
+        --plugin-secret datasette-auth-github client_secret your_client_secret
 
 datasette package
 =================