Deprecation (and future removal?) of gh-deploy command

[Andre601]

Ever since the gh-deploy command was added has GitHub evolved significantly.

First by the implementation of GitHub Actions, adding a CI/CD system one can use to automatically deploy their docs, and later with the ability to directly deploy to the GitHub Pages Environment, eliminating the need of having a gh-pages branch to begin with.
In fact, using the branch/folder aproach today is nothing more than using a pre-made Actions workflow from GitHub to deploy the site content.

The command was useful back when Actions and the direct deployment were not a thing, but today does it seem really dated and no longer like something needed, especially since it lacks any level of customization one may want to have when deploying sites, such as adding pages after build that MkDocs would've skipped/not included (dot-files f.e.).

So I propose that the gh-deploy command is being deprecated, adding a warning to inform that it's no longer recommended to be used.

The only reason for it to still exist, is for maybe some inexperienced user wanting to quickly deploy their page to GitHub.

Tho, I feel like the command also shouldn't be called gh-deploy anymore. It makes it seem like it's only for GitHub, when in actuality it's kind of a glorified collection of Git Commands being run to commit and push to a specific branch, which can be altered anyways.
So a more generic deploy command may be something else to consider. Tho, I would still argue, that such commands have become obsolete with GitHub Actions, Woodpecker-CI and Forgejo Actions existing and offering customization this command could never provide.

tl;dr: Consider deprecating the gh-deploy command in favour of more customizable CI/CD setups.
(Maybe even add a page in docs to include common setups for such systems?)

[DevTwilight]

i agree

[joapuiib]

I've moved away from mkdocs gh-deploy for publishing my sites.

Here's the GitHub Actions workflow I use for deploying, in case it helps someone:

name: deploy
on:
  push:
    branches:
      - main
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: github-pages
  cancel-in-progress: true

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: actions/setup-python@v5
        with:
          python-version: 3.x
          cache: 'pip'
      - name: Install dependencies
        run: pip install -r requirements.txt
      - name: Build
        run: mkdocs build --clean
      - name: Upload static files as artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: ./site/

  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    needs: build
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

[joapuiib]

I followed the guide in Using custom workflows with GitHub Pages and adapted it for building MkDocs.

But yeah, it could be written as a single job.

[DevTwilight]

@Andre601 this is cleaner instead of gh-deploy and since everyone uses github it should be not difficult

[Andre601]

@Andre601 this is cleaner instead of gh-deploy and since everyone uses github it should be not difficult

I mean, I started to prefer codeberg over github, but I get you.

[DevTwilight]

I mean, I started to prefer codeberg over github, but I get you.

i think Codeberg has same feature named Codeberg Pages
and by github i meant any vcs that has ci integration and pages feature

[Andre601]

i think Codeberg has same feature named Codeberg Pages and by github i meant any vcs that has ci integration and pages feature

It's similar, yeah, but has some minor, yet important differences. But that would be off-topic for this discussion, so I won't go into detail here.

[jimporter]

As the maintainer of mike (the MkDocs multi-version wrapper that uses something like gh-deploy under the hood), this makes sense to me overall. Pushing generated docs to gh-pages was always a bit of a hack.

However, it's a depressing sign of the times in the software industry when the old way (a single command) is replaced with 40-odd lines of YAML soup. I don't know if it's really ProperDocs' responsibility to have a more concise way to deploy documentation, but it's certainly something occupying my mind as I consider the future of mike. (I'd really like mike to be able to handle multiple doc frameworks as well as multiple deploy targets, if only for my own selfish reasons.)

[oprypin]

@jimporter Glad to see you here

Do you use gh-deploy or merely something like it? Either way this should not affect you.

Why the YAML soup is needed:

• It's what the leading provider of free VMs dictates.

• The YAML is not entirely meaningless, it really improves isolation of steps.

• It's nice to also populate the website exactly as the commits come in and there'll be some YAML no matter what

[jimporter]

Just "something like it". I forked (and eventually completely rewrote) the ghp_import package from way back. (At the time, it was vendored in MkDocs.) I should be entirely unaffected by any changes here, but I support the general plan. There's no reason to encourage people to put their generated docs in gh-pages anymore.

As for the YAML soup, it's certainly not a GitHub-only problem. Most (all?) CI platforms do something like it. I've just never been satisfied with how we all have to configure our CI jobs, but then again it's not like I've come up with anything better.

[Andre601]

One small thing I want to say, is that not everyone hosts their pageon GitHub, so there may not even be a dedicated branch for the site, making Mike a little less useful.

[jimporter]

Yeah, that's something I've been thinking about too. I'm slowly moving my work off of GitHub and over to Sourcehut, which naturally has a different mechanism for hosting docs. In addition, I hope to rewrite mike into something that support multiple doc frameworks, which would make it easy for ProperDocs and Zensical to work by hooking into the relevant places.

[oprypin]

Here's my current thinking:

• Removal of gh-deploy is just not happening in the near future because that's a breakage that doesn't achieve anything.

• The body of code is small (something like 150 lines I think) and can be made to work without dependencies and frozen in time. So it's not a liability.

• Sure, the command can be fully discouraged.

• No idea what a deprecation would even look like "physically". An INFO message? OK sure