| 1 | # g1t/deploy |
| 2 | |
| 3 | Builds the checkout a g1t Actions job is in and puts it on |
| 4 | [g1t.page](https://docs.g1t.sh/guides/deployments/): production when the |
| 5 | run is on the project's production branch, the pull request's preview for |
| 6 | a pull request's run, and the branch's preview for a run on any other |
| 7 | branch. |
| 8 | |
| 9 | ```yaml |
| 10 | name: Deploy |
| 11 | |
| 12 | on: |
| 13 | push: |
| 14 | branches: [main] |
| 15 | pull_request: |
| 16 | |
| 17 | permissions: |
| 18 | contents: read |
| 19 | deployments: write |
| 20 | |
| 21 | jobs: |
| 22 | deploy: |
| 23 | runs-on: ubuntu-latest |
| 24 | steps: |
| 25 | - uses: actions/checkout@v5 |
| 26 | - id: deploy |
| 27 | uses: g1t/deploy@v1 |
| 28 | - run: echo "Live at ${{ steps.deploy.outputs.url }}" |
| 29 | ``` |
| 30 | |
| 31 | The project must have Deployments on, and the workspace's plan must |
| 32 | include them. The guide, |
| 33 | [Deploying from a workflow](https://docs.g1t.sh/guides/deployments/#deploying-from-a-workflow), |
| 34 | says what is built and when. |
| 35 | |
| 36 | ## Inputs |
| 37 | |
| 38 | | Input | Default | | |
| 39 | | --- | --- | --- | |
| 40 | | `project` | The repository's one project with Deployments on | The project's slug. Needed when the repository has several. | |
| 41 | | `root-dir` | The project's setting | Where the project is in the checkout. | |
| 42 | | `build-command` | The project's setting, else what the build finds | What builds it. | |
| 43 | | `output-dir` | The project's setting, else the first of `dist`, `build`, `out`, `public`, `_site`, `.output/public` | The folder a static build writes. | |
| 44 | | `sha` | The run's commit | The commit this is a build of, for its `g1t / deploy` check. | |
| 45 | | `token` | `${{ github.token }}` | The job's own token. It needs `deployments: write`; any other token is refused. | |
| 46 | |
| 47 | ## Outputs |
| 48 | |
| 49 | | Output | | |
| 50 | | --- | --- | |
| 51 | | `url` | Where the app is served. | |
| 52 | | `deployment-id` | The build's id, `dpl_…`. | |
| 53 | | `kind` | `production` or `preview`. | |
| 54 | |
| 55 | ## How it works |
| 56 | |
| 57 | 1. It calls `POST /repos/{owner}/{repo}/deployments/builds` with the job's |
| 58 | token. g1t checks the plan and the spend limit, decides production or |
| 59 | preview from the run, sets the commit's `g1t / deploy` check to pending, |
| 60 | and answers with a token for this build alone and the project's |
| 61 | variables and secrets for builds of that kind. |
| 62 | 2. It masks that token and every secret with `::add-mask::`. |
| 63 | 3. It runs `g1t-runner deploy` in the checkout, which installs, builds and |
| 64 | uploads the app exactly as g1t's own builds do, and reports to g1t with |
| 65 | the build's token. The build's log is in the step's. |
| 66 | |
| 67 | A pull request from a fork or from someone without the Write role, and a |
| 68 | run that had to be approved, build without the project's secrets. The |
| 69 | build's time is the job's Actions time; it is not charged again. |
| 70 | |
| 71 | `g1t-runner` is on g1t's machines. Elsewhere (a self-hosted runner), the |
| 72 | action uses the one on `PATH`, or downloads the newest release from |
| 73 | `https://g1t.sh/downloads/runner/latest/` and checks it against the |
| 74 | release's `SHA256SUMS`. It runs on Linux and macOS, with `curl` and either |
| 75 | `jq` or `python3`. |