diff --git a/docs/userGuide/deployingTheSite.md b/docs/userGuide/deployingTheSite.md index e4a3eac0dd..d87d5df3fa 100644 --- a/docs/userGuide/deployingTheSite.md +++ b/docs/userGuide/deployingTheSite.md @@ -65,11 +65,41 @@ You can override the default deployment settings %%(e.g., repo/branch to deploy) ### Deploying to GitHub Pages via CI Tools **You can setup CI Tools to automatically build and deploy your site on GitHub Pages every time your GitHub repo is updated.** - + -Markbind currently supports deploying to Github Pages via [Travis CI](https://www.travis-ci.com/) or [AppVeyor CI](https://www.appveyor.com/). +To instruct [Github Actions](https://docs.github.com/en/actions) to build and deploy the site when you push to the repository, add a Github Actions workflow file in your project repo at the location `/.github/workflows/deploy.yml` A sample workflow file is provided below: +``` +name: Deploy Markbind Site +on: + push: + branches: master + +jobs: + build: + runs-on: ubuntu-latest + name: test + env: + GITHUB_TOKEN: {% raw %}${{ secrets.GITHUB_TOKEN }}{% endraw %} + steps: + - uses: actions/checkout@v2 + - uses: actions/setup-node@v2 + with: + node-version: '10' + - run: npm i -g markbind-cli + - run: markbind build + - run: markbind deploy --ci +``` + + + +The sample `deploy.yml` workflow above uses the [default Github Token secret](https://docs.github.com/en/actions/reference/authentication-in-a-workflow) that is generated automatically for each Github Actions workflow. You may also use a Github Personal Access Token in place of the default Github Token. For steps on setting up your Github Personal Access Token, you may refer to the [setup instructions for Travis CI](#configuring-your-repository-in-travis-ci). +Once you have created the file, commit and push the file to your repo. Github Actions should start to build and deploy your markbind site. You can verify this by visiting `www.github.com///actions`. + +For more information on customizing your workflow file to fit your specific needs, you may refer to the [Github Action Docs](https://docs.github.com/en/actions/reference/workflow-syntax-for-github-actions). + + diff --git a/packages/core/src/Site/index.js b/packages/core/src/Site/index.js index 466742da8f..81fac27d33 100644 --- a/packages/core/src/Site/index.js +++ b/packages/core/src/Site/index.js @@ -1174,11 +1174,22 @@ class Site { name: 'AppVeyorBot', email: 'deploy@appveyor.com', }; + } else if (process.env.GITHUB_ACTIONS) { + if (options.repo) { + repoSlug = Site.extractRepoSlug(options.repo); + } else { + repoSlug = process.env.GITHUB_REPOSITORY; + } + + options.user = { + name: 'github-actions', + email: 'github-actions@github.com', + }; } else { throw new Error('-c/--ci should only be run in CI environments.'); } - options.repo = `https://${githubToken}@github.com/${repoSlug}.git`; + options.repo = `https://x-access-token:${githubToken}@github.com/${repoSlug}.git`; } publish(basePath, options); diff --git a/packages/core/test/unit/Site.test.js b/packages/core/test/unit/Site.test.js index 7637747b86..047cf87dd5 100644 --- a/packages/core/test/unit/Site.test.js +++ b/packages/core/test/unit/Site.test.js @@ -282,11 +282,13 @@ describe('Site deploy with various CI environments', () => { beforeEach(() => { // Delete all environment variables that affect tests - delete process.env.TRAVIS; delete process.env.GITHUB_TOKEN; + delete process.env.TRAVIS; delete process.env.TRAVIS_REPO_SLUG; delete process.env.APPVEYOR; delete process.env.APPVEYOR_REPO_NAME; + delete process.env.GITHUB_ACTIONS; + delete process.env.GITHUB_REPOSITORY; }); afterAll(() => { @@ -297,6 +299,7 @@ describe('Site deploy with various CI environments', () => { test.each([ ['TRAVIS', 'TRAVIS_REPO_SLUG', { name: 'Deployment Bot', email: 'deploy@travis-ci.org' }], ['APPVEYOR', 'APPVEYOR_REPO_NAME', { name: 'AppVeyorBot', email: 'deploy@appveyor.com' }], + ['GITHUB_ACTIONS', 'GITHUB_REPOSITORY', { name: 'github-actions', email: 'github-actions@github.com' }], ])('Site deploy -c/--ci deploys with default settings', async (ciIdentifier, repoSlugIdentifier, deployBotUser) => { process.env[ciIdentifier] = true; @@ -312,13 +315,15 @@ describe('Site deploy with various CI environments', () => { const site = new Site('./', '_site'); await site.deploy(true); expect(ghpages.options.repo) - .toEqual(`https://${process.env.GITHUB_TOKEN}@github.com/${process.env[repoSlugIdentifier]}.git`); + // eslint-disable-next-line max-len + .toEqual(`https://x-access-token:${process.env.GITHUB_TOKEN}@github.com/${process.env[repoSlugIdentifier]}.git`); expect(ghpages.options.user).toEqual(deployBotUser); }); test.each([ ['TRAVIS', 'TRAVIS_REPO_SLUG'], ['APPVEYOR', 'APPVEYOR_REPO_NAME'], + ['GITHUB_ACTIONS', 'GITHUB_REPOSITORY'], ])('Site deploy -c/--ci deploys with custom GitHub repo', async (ciIdentifier, repoSlugIdentifier) => { process.env[ciIdentifier] = true; @@ -336,12 +341,13 @@ describe('Site deploy with various CI environments', () => { const site = new Site('./', '_site'); await site.deploy(true); expect(ghpages.options.repo) - .toEqual(`https://${process.env.GITHUB_TOKEN}@github.com/USER/REPO.git`); + .toEqual(`https://x-access-token:${process.env.GITHUB_TOKEN}@github.com/USER/REPO.git`); }); test.each([ ['TRAVIS', 'TRAVIS_REPO_SLUG'], ['APPVEYOR', 'APPVEYOR_REPO_NAME'], + ['GITHUB_ACTIONS', 'GITHUB_REPOSITORY'], ])('Site deploy -c/--ci deploys to correct repo when .git is in repo name', async (ciIdentifier, repoSlugIdentifier) => { process.env[ciIdentifier] = true; @@ -357,7 +363,8 @@ describe('Site deploy with various CI environments', () => { const site = new Site('./', '_site'); await site.deploy(true); expect(ghpages.options.repo) - .toEqual(`https://${process.env.GITHUB_TOKEN}@github.com/${process.env[repoSlugIdentifier]}.git`); + // eslint-disable-next-line max-len + .toEqual(`https://x-access-token:${process.env.GITHUB_TOKEN}@github.com/${process.env[repoSlugIdentifier]}.git`); }); test('Site deploy -c/--ci should not deploy if not in CI environment', async () => { @@ -378,6 +385,7 @@ describe('Site deploy with various CI environments', () => { test.each([ ['TRAVIS'], ['APPVEYOR'], + ['GITHUB_ACTIONS'], ])('Site deploy -c/--ci should not deploy without authentication token', async (ciIdentifier) => { process.env[ciIdentifier] = true; @@ -396,6 +404,7 @@ describe('Site deploy with various CI environments', () => { test.each([ ['TRAVIS'], ['APPVEYOR'], + ['GITHUB_ACTIONS'], ])('Site deploy -c/--ci should not deploy if custom repository is not on GitHub', async (ciIdentifier) => { process.env[ciIdentifier] = true; process.env.GITHUB_TOKEN = 'githubToken';