diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index b690fc4..8f0d9bb 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -8,7 +8,7 @@ jobs: runs-on: ubuntu-latest steps: - name: Check out code - uses: actions/checkout@v2.3.3 + uses: actions/checkout@v3.0.2 - name: Shellcheck run: | diff --git a/Dockerfile b/Dockerfile index 41da0bc..69c125c 100644 --- a/Dockerfile +++ b/Dockerfile @@ -1,11 +1,10 @@ -FROM python:3.8.1-alpine3.11 +FROM python:3.11-alpine3.18 LABEL maintainer="Michael Hausenblas, hausenbl@amazon.com" -RUN apk add --no-cache git git-fast-import openssh build-base WORKDIR /docs COPY action.sh /action.sh -RUN apk add --no-cache bash && chmod +x /action.sh +RUN apk add --no-cache bash git git-fast-import openssh build-base && chmod +x /action.sh ENTRYPOINT ["/action.sh"] diff --git a/README.md b/README.md index a85a290..bc5ca6e 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # GitHub Action to deploy an MkDocs site to GitHub Pages -![GitHub Badge](https://github.com/mhausenblas/mkdocs-deploy-gh-pages/workflows/Build/badge.svg) +![GitHub Badge](https://github.com/andi34/mkdocs-deploy-gh-pages/workflows/Build/badge.svg) This GitHub action will deploy your [MkDocs site](https://www.mkdocs.org/) as [GitHub Pages](https://pages.github.com/), using the [Material](https://github.com/squidfunk/mkdocs-material) theme. It assumes that an `mkdocs.yml` file is present in the top-level directory and the source files (Markdown, etc.) are in the `docs/` folder. You can use [mhausenblas/mkdocs-template](https://github.com/mhausenblas/mkdocs-template) as a template. @@ -20,8 +20,18 @@ This action supports building and deploying with a `GITHUB_TOKEN`. This token is It is more **secure** than a personal token, since you never actually see the value of the `GITHUB_TOKEN` and also the `GITHUB_TOKEN` is scoped to only work for a **single** repo. +You may need to give the `GITHUB_TOKEN` write permission. Go to your repository's **Settings > Actions > General > Workflow Permissions** and select **Read and write permissions**. + Note that for this approach, Github Pages will be enabled in Settings but you will _not_ have a URL displayed or environment tab yet. So change the Github Pages settings to another target and then back again to `gh-pages` (if that is your branch to serve) - then you will see a URL. This step is only needed on the _first_ deploy and no action is needed later on. +### Alternative `GITHUB_DOMAIN` + +In case this action should be used in a Github Enterprise environment you can overwrite the `github.com` domain with your corresponding Github Enterprise domain name by specifying the `GITHUB_DOMAIN` environment variable. + +### Custom repository + +In case you want to push to another repository than origin define `GITHUB_ORIGIN`. Needs building with `PERSONAL_TOKEN`. + ### Custom domain for github pages MkDocs can be deployed to github pages using a custom domain, if you populate a `CUSTOM_DOMAIN` environment variable. This will generate a CNAME file, which will be placed inside the `/docs` folder. @@ -36,6 +46,10 @@ This action supports deployment of mkdocs with different file path , if you popu Some Python packages require C bindings. These packages can be installed using the `EXTRA_PACKAGES` variable. The `EXTRA_PACKAGES` variable will be passed to the `apk add` command of Alpine Linux before running `pip install` to install the Python packages. +## Installing mkdocs plugins + +If you use some mkdocs plugins like [`codeinclude`](https://github.com/rnorth/mkdocs-codeinclude-plugin) then you need to define it as dependency in the typical python way with a `requirements.txt` file. In the sample above you need to add the line `mkdocs-codeinclude-plugin`. Then you need to link the file using the `REQUIREMENTS` variable. + ## Example usage ```shell @@ -51,13 +65,20 @@ jobs: runs-on: ubuntu-latest steps: - name: Checkout main - uses: actions/checkout@v1 + uses: actions/checkout@v4 + with: + token: ${{ secrets.PAT_TOKEN }} # Uses Personal Access Token (PAT) for checkout, needed to push to another repository - name: Deploy docs - uses: mhausenblas/mkdocs-deploy-gh-pages@master + uses: andi34/mkdocs-deploy-gh-pages@nomaterial + # Or use andi34/mkdocs-deploy-gh-pages@master to build with the mkdocs-material theme env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + # PERSONAL_TOKEN: ${{ secrets.PAT_TOKEN }} CUSTOM_DOMAIN: optionaldomain.com CONFIG_FILE: folder/mkdocs.yml EXTRA_PACKAGES: build-base + # GITHUB_DOMAIN: github.myenterprise.com + # GITHUB_ORIGIN: destination-repository-username/destination-repository-name + REQUIREMENTS: folder/requirements.txt ``` diff --git a/action.sh b/action.sh old mode 100644 new mode 100755 index d96343e..25ce0be --- a/action.sh +++ b/action.sh @@ -6,9 +6,13 @@ function print_info() { echo -e "\e[36mINFO: ${1}\e[m" } -if [ -n "${EXTRA_PACKAGES}" ]; then - apk add --no-cache ${EXTRA_PACKAGES} -fi +for package in ${EXTRA_PACKAGES} +do + apk add --no-cache "${package}" +done + +# mkdocs is required +pip install mkdocs if [ -n "${REQUIREMENTS}" ] && [ -f "${GITHUB_WORKSPACE}/${REQUIREMENTS}" ]; then pip install -r "${GITHUB_WORKSPACE}/${REQUIREMENTS}" @@ -31,20 +35,33 @@ else export CONFIG_FILE="${GITHUB_WORKSPACE}/mkdocs.yml" fi +if [ -n "${GITHUB_ORIGIN}" ]; then + print_info "setup with GITHUB_ORIGIN" +else + print_info "setup with GITHUB_REPOSITORY" + export GITHUB_ORIGIN=${GITHUB_REPOSITORY} +fi + if [ -n "${GITHUB_TOKEN}" ]; then print_info "setup with GITHUB_TOKEN" - remote_repo="https://x-access-token:${GITHUB_TOKEN}@github.com/${GITHUB_REPOSITORY}.git" + remote_repo="https://x-access-token:${GITHUB_TOKEN}@${GITHUB_DOMAIN:-"github.com"}/${GITHUB_ORIGIN}.git" elif [ -n "${PERSONAL_TOKEN}" ]; then print_info "setup with PERSONAL_TOKEN" - remote_repo="https://x-access-token:${PERSONAL_TOKEN}@github.com/${GITHUB_REPOSITORY}.git" + remote_repo="https://x-access-token:${PERSONAL_TOKEN}@${GITHUB_DOMAIN:-"github.com"}/${GITHUB_ORIGIN}.git" +else + print_info "no token found; linting" + exec -- mkdocs build --config-file "${CONFIG_FILE}" fi +# workaround, see https://github.com/actions/checkout/issues/766 +git config --global --add safe.directory "$GITHUB_WORKSPACE" + if ! git config --get user.name; then git config --global user.name "${GITHUB_ACTOR}" fi if ! git config --get user.email; then - git config --global user.email "${GITHUB_ACTOR}@users.noreply.github.com" + git config --global user.email "${GITHUB_ACTOR}@users.noreply.${GITHUB_DOMAIN:-"github.com"}" fi git remote rm origin