Add a bunch more details on how to use the tool to the readme.

2020-08-24 13:49:19 +01:00 · 2020-08-24 13:49:19 +01:00 · 5cbe859953
--- a/README.md
+++ b/README.md
@ -1,2 +1,43 @@
 # CodeQL Action Sync Tool
-A tool for syncing the [CodeQL Action](https://github.com/github/codeql-action/) from GitHub.com to GitHub Enterprise Server, including copying the CodeQL bundle.
+![Logo](docs/logo.png)
+
+A tool for syncing the [CodeQL Action](https://github.com/github/codeql-action/) from GitHub.com to GitHub Enterprise Server, including copying the CodeQL bundle. This allows the CodeQL Action to work even if your GitHub Enterprise Server or GitHub Actions runners do not have internet access.
+
+## Installation
+The CodeQL Action sync tool can be downloaded from the [releases page](https://github.com/github/codeql-action-sync-tool/releases/latest/) of this repository.
+
+## Usage
+The sync tool can be used in two different ways.
+
+If you have a machine that is able to access GitHub.com and the GitHub Enterprise Server instance then simply follow the steps under ["I have a machine that can access both GitHub.com and GitHub Enterprise Server"](#i-have-a-machine-that-can-access-both-githubcom-and-github-enterprise-server).
+
+If your GitHub Enterprise Server instance is on a completely isolated network where no machines have access to both GitHub.com and GitHub Enterprise Server then follow the steps under ["I don't have a machine that can access both GitHub.com and GitHub Enterprise Server"](#i-dont-have-a-machine-that-can-access-both-githubcom-and-github-enterprise-server) instead.
+
+### I have a machine that can access both GitHub.com and GitHub Enterprise Server.
+From a machine with access to both GitHub.com and GitHub Enterprise Server use the `./codeql-action-sync sync` command to copy the CodeQL Action and bundles.
+
+**Required Arguments:**
+* `--destination-url` - The URL of the GitHub Enterprise Server instance to push the Action to.
+* `--destination-token` - A [Personal Access Token](https://docs.github.com/en/enterprise/user/github/authenticating-to-github/creating-a-personal-access-token) for the destination GitHub Enterprise Server instance. The token should be granted at least the `public_repo` scope. If the destination repository is in an organization that does not yet exist, your token will need to have the `site_admin` scope in order to create the organization. The organization can also be created manually or an existing organization used.
+
+**Optional Arguments:**
+* `--cache-dir` - A temporary directory in which to store data downloaded from GitHub.com before it is uploaded to GitHub Enterprise Server. If not specified a directory next to the sync tool will be used.
+* `--destination-repository` - The name of the repository in which to create or update the CodeQL Action. If not specified `github/codeql-action` will be used.
+
+### I don't have a machine that can access both GitHub.com and GitHub Enterprise Server.
+From a machine with access to GitHub.com use the `./codeql-action-sync pull` command to download a copy of the CodeQL Action and bundles to a local folder.
+
+**Optional Arguments:**
+* `--cache-dir` - The directory in which to store data downloaded from GitHub.com. If not specified a directory next to the sync tool will be used.
+
+Next copy the sync tool and cache directory to another machine which has access to GitHub Enterprise Server.
+
+Now use the `./codeql-action-sync push` command to upload the CodeQL Action and bundles to GitHub Enterprise Server.
+
+**Required Arguments:**
+* `--destination-url` - The URL of the GitHub Enterprise Server instance to push the Action to.
+* `--destination-token` - A [Personal Access Token](https://docs.github.com/en/enterprise/user/github/authenticating-to-github/creating-a-personal-access-token) for the destination GitHub Enterprise Server instance. The token should be granted at least the `public_repo` scope. If the destination repository is in an organization that does not yet exist, your token will need to have the `site_admin` scope in order to create the organization. The organization can also be created manually or an existing organization used.
+
+**Optional Arguments:**
+* `--cache-dir` - The directory to which the Action was previously downloaded.
+* `--destination-repository` - The name of the repository in which to create or update the CodeQL Action. If not specified `github/codeql-action` will be used.
--- a/docs/logo.png
+++ b/docs/logo.png
--- a/docs/logo.svg
+++ b/docs/logo.svg
@ -0,0 +1,361 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<svg
+   xmlns:dc="http://purl.org/dc/elements/1.1/"
+   xmlns:cc="http://creativecommons.org/ns#"
+   xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+   xmlns:svg="http://www.w3.org/2000/svg"
+   xmlns="http://www.w3.org/2000/svg"
+   xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
+   xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+   width="150"
+   height="56"
+   viewBox="0 0 150 56"
+   version="1.1"
+   id="svg36"
+   sodipodi:docname="logo.svg"
+   inkscape:export-filename="/home/chris/Downloads/Code QL.svg.png"
+   inkscape:export-xdpi="96"
+   inkscape:export-ydpi="96"
+   inkscape:version="0.92.3 (2405546, 2018-03-11)">
+  <g
+     id="light"
+     style="fill:none;fill-rule:evenodd;stroke:none;stroke-width:1"
+     transform="translate(-0.237,1.000144)">
+    <g
+       id="Titles"
+       transform="translate(-587,-1523)"
+       style="opacity:0.59735401" />
+    <g
+       id="Slides"
+       transform="translate(-570,-1589)" />
+    <g
+       id="Code-QL"
+       transform="translate(5,5)">
+      <rect
+         id="Rectangle-41"
+         x="0"
+         y="0"
+         width="24"
+         height="14"
+         rx="2"
+         style="stroke:#2088ff;stroke-width:2;stroke-linecap:round;stroke-linejoin:round" />
+      <path
+         d="m 2,18 v 22 c 0,1.104569 0.8954305,2 2,2 h 8 v 0"
+         id="Path-9"
+         inkscape:connector-curvature="0"
+         style="fill-rule:nonzero;stroke:#79b8ff;stroke-width:2;stroke-linecap:round;stroke-linejoin:round" />
+      <line
+         x1="7"
+         y1="19"
+         x2="24"
+         y2="19"
+         id="Stroke-13"
+         style="stroke:#79b8ff;stroke-width:2;stroke-linecap:round;stroke-linejoin:round" />
+      <line
+         x1="11"
+         y1="24"
+         x2="31"
+         y2="24"
+         id="line11"
+         style="stroke:#79b8ff;stroke-width:2;stroke-linecap:round;stroke-linejoin:round" />
+      <line
+         x1="11"
+         y1="29"
+         x2="31"
+         y2="29"
+         id="line13"
+         style="stroke:#79b8ff;stroke-width:2;stroke-linecap:round;stroke-linejoin:round" />
+      <line
+         x1="28"
+         y1="9"
+         x2="31"
+         y2="9"
+         id="line15"
+         style="stroke:#79b8ff;stroke-width:2;stroke-linecap:round;stroke-linejoin:round" />
+      <line
+         x1="28"
+         y1="14"
+         x2="38"
+         y2="14"
+         id="Stroke-15"
+         style="stroke:#79b8ff;stroke-width:2;stroke-linecap:round;stroke-linejoin:round" />
+      <line
+         x1="7"
+         y1="34"
+         x2="17"
+         y2="34"
+         id="line18"
+         style="stroke:#79b8ff;stroke-width:2;stroke-linecap:round;stroke-linejoin:round" />
+      <path
+         d="m 28,4 v 24 c 0,1.104569 0.89543,2 2,2 h 14 v 0"
+         id="path20"
+         transform="rotate(180,36,17)"
+         inkscape:connector-curvature="0"
+         style="fill-rule:nonzero;stroke:#79b8ff;stroke-width:2;stroke-linecap:round;stroke-linejoin:round" />
+      <line
+         x1="38"
+         y1="37.999756"
+         x2="31"
+         y2="37.999756"
+         id="Path"
+         style="stroke:#2088ff;stroke-width:2;stroke-linecap:round;stroke-linejoin:round" />
+      <line
+         x1="42"
+         y1="41.999756"
+         x2="34"
+         y2="41.999756"
+         id="line23"
+         style="stroke:#2088ff;stroke-width:2;stroke-linecap:round;stroke-linejoin:round" />
+      <path
+         d="M 37.865967,33.999756 H 44 c 1.104569,0 2,0.89543 2,2 v 8 c 0,1.104569 -0.895431,2 -2,2 h -5.308838 m 1.764404,0 H 34 m -5,-12 h 10.447754"
+         id="Shape"
+         inkscape:connector-curvature="0"
+         style="stroke:#2088ff;stroke-width:2;stroke-linecap:round" />
+      <line
+         x1="16"
+         y1="5"
+         x2="18"
+         y2="5"
+         id="line26"
+         style="stroke:#2088ff;stroke-width:2;stroke-linecap:round;stroke-linejoin:round" />
+      <line
+         x1="16"
+         y1="9"
+         x2="20"
+         y2="9"
+         id="line28"
+         style="stroke:#2088ff;stroke-width:2;stroke-linecap:round;stroke-linejoin:round" />
+      <path
+         d="m 7.8522727,7 c 0,0.518942 -0.082385,0.9753768 -0.2471591,1.3693182 C 7.4403401,8.7632596 7.2159105,9.0871199 6.9318182,9.3409091 L 7.7642045,10.386364 H 6.6164773 L 6.1477273,9.8096591 C 5.8314378,9.9289779 5.4914791,9.9886364 5.1278409,9.9886364 4.6107929,9.9886364 4.1467824,9.8712133 3.7357955,9.6363636 3.3248086,9.401514 3.0000012,9.0610818 2.7613636,8.6150568 2.5227261,8.1690319 2.4034091,7.630685 2.4034091,7 c 0,-0.6344729 0.119317,-1.1742402 0.3579545,-1.6193182 0.2386376,-0.445078 0.563445,-0.7845632 0.9744319,-1.0184659 0.4109869,-0.2339027 0.8749974,-0.3508523 1.3920454,-0.3508523 0.5151541,0 0.9782176,0.1169496 1.3892046,0.3508523 C 6.9280324,4.5961186 7.2533132,4.9356038 7.4928977,5.3806818 7.7324823,5.8257598 7.8522727,6.3655271 7.8522727,7 Z M 4.7017045,7.8863636 H 5.7471591 L 6.1789773,8.4403409 C 6.3134476,8.2793553 6.4180867,8.0785997 6.4928977,7.8380682 6.5677087,7.5975367 6.6051136,7.3181834 6.6051136,7 6.6051136,6.3825727 6.4706453,5.91146 6.2017045,5.5866477 5.9327638,5.2618355 5.5748128,5.0994318 5.1278409,5.0994318 4.680869,5.0994318 4.322918,5.2618355 4.0539773,5.5866477 3.7850365,5.91146 3.6505682,6.3825727 3.6505682,7 c 0,0.6155334 0.1344683,1.0861726 0.4034091,1.4119318 0.2689407,0.3257592 0.6268917,0.4886364 1.0738636,0.4886364 0.111743,0 0.2178025,-0.010417 0.3181818,-0.03125 z M 9.1813315,10 V 4 h 1.2301135 v 4.9857955 h 2.494318 V 10 Z"
+         id="QL"
+         inkscape:connector-curvature="0"
+         style="fill:#2088ff;fill-rule:nonzero" />
+      <path
+         d="m 21.344687,34.903437 -5.29021,7.992425 c -0.609664,0.921077 -0.357213,2.161988 0.563864,2.771652 0.32738,0.216694 0.711296,0.332242 1.103894,0.332242 h 10.56249 c 1.10457,0 2,-0.895431 2,-2 0,-0.391535 -0.114923,-0.774459 -0.33052,-1.101289 l -5.27228,-7.992424 c -0.608225,-0.922028 -1.84874,-1.176416 -2.770768,-0.568192 -0.225008,0.148429 -0.41769,0.34081 -0.56647,0.565586 z"
+         id="Path-72"
+         inkscape:connector-curvature="0"
+         style="stroke:#2088ff;stroke-width:2;stroke-linejoin:round" />
+      <line
+         x1="22.992798"
+         y1="38"
+         x2="22.992798"
+         y2="40"
+         id="Stroke-11"
+         transform="matrix(1,0,0,-1,0,78)"
+         style="stroke:#2088ff;stroke-width:2;stroke-linecap:round;stroke-linejoin:round" />
+      <path
+         d="m 23,44 c 0.552285,0 1,-0.447715 1,-1 0,-0.552285 -0.447715,-1 -1,-1 -0.552285,0 -1,0.447715 -1,1 0,0.552285 0.447715,1 1,1 z"
+         id="Oval-10"
+         transform="matrix(1,0,0,-1,0,86)"
+         inkscape:connector-curvature="0"
+         style="fill:#2088ff" />
+    </g>
+  </g>
+  <metadata
+     id="metadata42">
+    <rdf:RDF>
+      <cc:Work
+         rdf:about="">
+        <dc:format>image/svg+xml</dc:format>
+        <dc:type
+           rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
+        <dc:title>Code QL</dc:title>
+      </cc:Work>
+    </rdf:RDF>
+  </metadata>
+  <defs
+     id="defs40">
+    <marker
+       inkscape:stockid="TriangleOutL"
+       orient="auto"
+       refY="0.0"
+       refX="0.0"
+       id="TriangleOutL"
+       style="overflow:visible"
+       inkscape:isstock="true">
+      <path
+         id="path1165"
+         d="M 5.77,0.0 L -2.88,5.0 L -2.88,-5.0 L 5.77,0.0 z "
+         style="fill-rule:evenodd;stroke:#767676;stroke-width:1pt;stroke-opacity:1;fill:#767676;fill-opacity:1"
+         transform="scale(0.8)" />
+    </marker>
+    <marker
+       inkscape:stockid="Arrow1Lend"
+       orient="auto"
+       refY="0.0"
+       refX="0.0"
+       id="Arrow1Lend"
+       style="overflow:visible;"
+       inkscape:isstock="true">
+      <path
+         id="path1026"
+         d="M 0.0,0.0 L 5.0,-5.0 L -12.5,0.0 L 5.0,5.0 L 0.0,0.0 z "
+         style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt;stroke-opacity:1;fill:#000000;fill-opacity:1"
+         transform="scale(0.8) rotate(180) translate(12.5,0)" />
+    </marker>
+  </defs>
+  <sodipodi:namedview
+     pagecolor="#ffffff"
+     bordercolor="#666666"
+     borderopacity="1"
+     objecttolerance="10"
+     gridtolerance="10"
+     guidetolerance="10"
+     inkscape:pageopacity="0"
+     inkscape:pageshadow="2"
+     inkscape:window-width="2560"
+     inkscape:window-height="1365"
+     id="namedview38"
+     showgrid="false"
+     inkscape:zoom="4.2142857"
+     inkscape:cx="28"
+     inkscape:cy="28"
+     inkscape:window-x="1920"
+     inkscape:window-y="24"
+     inkscape:window-maximized="1"
+     inkscape:current-layer="svg36" />
+  <!-- Generator: Sketch 59 (86127) - https://sketch.com -->
+  <title
+     id="title2">Code QL</title>
+  <g
+     transform="translate(94.677966,1.000144)"
+     id="light-9"
+     style="fill:none;fill-rule:evenodd;stroke:none;stroke-width:1">
+    <g
+       id="Titles-2"
+       transform="translate(-587,-1523)"
+       style="opacity:0.59735401" />
+    <g
+       id="Slides-0"
+       transform="translate(-570,-1589)" />
+    <g
+       id="Code-QL-2"
+       transform="translate(5,5)">
+      <rect
+         id="Rectangle-41-3"
+         x="0"
+         y="0"
+         width="24"
+         height="14"
+         rx="2"
+         style="stroke:#2088ff;stroke-width:2;stroke-linecap:round;stroke-linejoin:round" />
+      <path
+         d="m 2,18 v 22 c 0,1.104569 0.8954305,2 2,2 h 8 v 0"
+         id="Path-9-7"
+         inkscape:connector-curvature="0"
+         style="fill-rule:nonzero;stroke:#79b8ff;stroke-width:2;stroke-linecap:round;stroke-linejoin:round" />
+      <line
+         x1="7"
+         y1="19"
+         x2="24"
+         y2="19"
+         id="Stroke-13-5"
+         style="stroke:#79b8ff;stroke-width:2;stroke-linecap:round;stroke-linejoin:round" />
+      <line
+         x1="11"
+         y1="24"
+         x2="31"
+         y2="24"
+         id="line11-9"
+         style="stroke:#79b8ff;stroke-width:2;stroke-linecap:round;stroke-linejoin:round" />
+      <line
+         x1="11"
+         y1="29"
+         x2="31"
+         y2="29"
+         id="line13-2"
+         style="stroke:#79b8ff;stroke-width:2;stroke-linecap:round;stroke-linejoin:round" />
+      <line
+         x1="28"
+         y1="9"
+         x2="31"
+         y2="9"
+         id="line15-2"
+         style="stroke:#79b8ff;stroke-width:2;stroke-linecap:round;stroke-linejoin:round" />
+      <line
+         x1="28"
+         y1="14"
+         x2="38"
+         y2="14"
+         id="Stroke-15-8"
+         style="stroke:#79b8ff;stroke-width:2;stroke-linecap:round;stroke-linejoin:round" />
+      <line
+         x1="7"
+         y1="34"
+         x2="17"
+         y2="34"
+         id="line18-9"
+         style="stroke:#79b8ff;stroke-width:2;stroke-linecap:round;stroke-linejoin:round" />
+      <path
+         d="m 28,4 v 24 c 0,1.104569 0.89543,2 2,2 h 14 v 0"
+         id="path20-7"
+         transform="rotate(180,36,17)"
+         inkscape:connector-curvature="0"
+         style="fill-rule:nonzero;stroke:#79b8ff;stroke-width:2;stroke-linecap:round;stroke-linejoin:round" />
+      <line
+         x1="38"
+         y1="37.999756"
+         x2="31"
+         y2="37.999756"
+         id="Path-3"
+         style="stroke:#2088ff;stroke-width:2;stroke-linecap:round;stroke-linejoin:round" />
+      <line
+         x1="42"
+         y1="41.999756"
+         x2="34"
+         y2="41.999756"
+         id="line23-6"
+         style="stroke:#2088ff;stroke-width:2;stroke-linecap:round;stroke-linejoin:round" />
+      <path
+         d="M 37.865967,33.999756 H 44 c 1.104569,0 2,0.89543 2,2 v 8 c 0,1.104569 -0.895431,2 -2,2 h -5.308838 m 1.764404,0 H 34 m -5,-12 h 10.447754"
+         id="Shape-1"
+         inkscape:connector-curvature="0"
+         style="stroke:#2088ff;stroke-width:2;stroke-linecap:round" />
+      <line
+         x1="16"
+         y1="5"
+         x2="18"
+         y2="5"
+         id="line26-2"
+         style="stroke:#2088ff;stroke-width:2;stroke-linecap:round;stroke-linejoin:round" />
+      <line
+         x1="16"
+         y1="9"
+         x2="20"
+         y2="9"
+         id="line28-9"
+         style="stroke:#2088ff;stroke-width:2;stroke-linecap:round;stroke-linejoin:round" />
+      <path
+         d="m 7.8522727,7 c 0,0.518942 -0.082385,0.9753768 -0.2471591,1.3693182 C 7.4403401,8.7632596 7.2159105,9.0871199 6.9318182,9.3409091 L 7.7642045,10.386364 H 6.6164773 L 6.1477273,9.8096591 C 5.8314378,9.9289779 5.4914791,9.9886364 5.1278409,9.9886364 4.6107929,9.9886364 4.1467824,9.8712133 3.7357955,9.6363636 3.3248086,9.401514 3.0000012,9.0610818 2.7613636,8.6150568 2.5227261,8.1690319 2.4034091,7.630685 2.4034091,7 c 0,-0.6344729 0.119317,-1.1742402 0.3579545,-1.6193182 0.2386376,-0.445078 0.563445,-0.7845632 0.9744319,-1.0184659 0.4109869,-0.2339027 0.8749974,-0.3508523 1.3920454,-0.3508523 0.5151541,0 0.9782176,0.1169496 1.3892046,0.3508523 C 6.9280324,4.5961186 7.2533132,4.9356038 7.4928977,5.3806818 7.7324823,5.8257598 7.8522727,6.3655271 7.8522727,7 Z M 4.7017045,7.8863636 H 5.7471591 L 6.1789773,8.4403409 C 6.3134476,8.2793553 6.4180867,8.0785997 6.4928977,7.8380682 6.5677087,7.5975367 6.6051136,7.3181834 6.6051136,7 6.6051136,6.3825727 6.4706453,5.91146 6.2017045,5.5866477 5.9327638,5.2618355 5.5748128,5.0994318 5.1278409,5.0994318 4.680869,5.0994318 4.322918,5.2618355 4.0539773,5.5866477 3.7850365,5.91146 3.6505682,6.3825727 3.6505682,7 c 0,0.6155334 0.1344683,1.0861726 0.4034091,1.4119318 0.2689407,0.3257592 0.6268917,0.4886364 1.0738636,0.4886364 0.111743,0 0.2178025,-0.010417 0.3181818,-0.03125 z M 9.1813315,10 V 4 h 1.2301135 v 4.9857955 h 2.494318 V 10 Z"
+         id="QL-3"
+         inkscape:connector-curvature="0"
+         style="fill:#2088ff;fill-rule:nonzero" />
+      <path
+         d="m 21.344687,34.903437 -5.29021,7.992425 c -0.609664,0.921077 -0.357213,2.161988 0.563864,2.771652 0.32738,0.216694 0.711296,0.332242 1.103894,0.332242 h 10.56249 c 1.10457,0 2,-0.895431 2,-2 0,-0.391535 -0.114923,-0.774459 -0.33052,-1.101289 l -5.27228,-7.992424 c -0.608225,-0.922028 -1.84874,-1.176416 -2.770768,-0.568192 -0.225008,0.148429 -0.41769,0.34081 -0.56647,0.565586 z"
+         id="Path-72-1"
+         inkscape:connector-curvature="0"
+         style="stroke:#2088ff;stroke-width:2;stroke-linejoin:round" />
+      <line
+         x1="22.992798"
+         y1="38"
+         x2="22.992798"
+         y2="40"
+         id="Stroke-11-9"
+         transform="matrix(1,0,0,-1,0,78)"
+         style="stroke:#2088ff;stroke-width:2;stroke-linecap:round;stroke-linejoin:round" />
+      <path
+         d="m 23,44 c 0.552285,0 1,-0.447715 1,-1 0,-0.552285 -0.447715,-1 -1,-1 -0.552285,0 -1,0.447715 -1,1 0,0.552285 0.447715,1 1,1 z"
+         id="Oval-10-4"
+         transform="matrix(1,0,0,-1,0,86)"
+         inkscape:connector-curvature="0"
+         style="fill:#2088ff" />
+    </g>
+  </g>
+  <desc
+     id="desc4">Created with Sketch.</desc>
+  <path
+     style="fill:none;stroke:#767676;stroke-width:1.1;stroke-linecap:butt;stroke-linejoin:round;stroke-opacity:1;marker-end:url(#TriangleOutL);stroke-miterlimit:4;stroke-dasharray:none;paint-order:stroke fill markers;"
+     d="m 55.288136,28.237288 h 32.98305"
+     id="path4073"
+     inkscape:connector-curvature="0" />
+</svg>