Forem: Jean-Francis Bastien

Docs as Code Confluence

Jean-Francis Bastien — Tue, 30 Nov 2021 00:41:44 +0000

Hi, as an introduction, I want to link a post that talked to me. How Google, Twitter, and Spotify built a culture of documentation

Since I read that article, I am looking for a way to introduce that concept to my team.

The concept and implementation are relatively easy to achieve with Github Pages, Netlify, Vercel, etc. When it comes to internal documentation, more requirements appear, for example, authorization. I also didn't want to introduce another place to look for documentation.

Since we have Confluence, the idea is to have the benefit of the concept of docs as code and keep all our documentation in the same place. Confluence will handle the "hosting", indexing and authorization.

My Workflow

Bhacaz / docs-as-code-confluence

Publish the content of a folder to confluence Github Action

Docs as Code - Confluence

Publish a folder of documentation to Confluence.

Create a Confluence Page for each markdown file. Each folder will create a parent page to reflect the directory structure.

Parameters

Name	Description	Required
`folder`	The folder to sync	true
`username`	Confluence username or email	true
`password`	Confluence password or API token	true
`confluence-base-url`	Your Confluence URL (with `wiki`). Example: `https://mydomain.atlassian.net/wiki`	true
`space-key`	Confluence space key to publish the documentation. Located after `spaces` in the URL. `https://mydomain.atlassian.net/wiki/spaces/<<~1234>>`. Or in Space settings > Space details > Key.	true
`parent-page-id`	Page id under which the documentation will be published. Located after `pages` in the URL. `https://mydomain.atlassian.net/wiki/spaces/~1234/pages/<<1234>>/My+Parent+Page`	true

TODO

Renaming a file
Moving/Removing a file
Not updating Confluence pages when there is no change
Add commit link to the new page version
Add markdown images with url source

Example of workflow

name: Sync Docs as Code -

…

View on GitHub

The action looks for a specific folder and publishes its contents to Confluence. It recreates the file structure and publishes the markdown content to a Confluence page.

Submission Category:

DIY Deployments

Yaml File or Link to Code

I create a minimal example of usage with a functional workflow, a docs folder with markdown files, and some screenshots of the result in Confluence.

Bhacaz / docs-as-code-confluence-demo

Additional Resources / Info

There are still some must-have features to implement, but it's a good start for writing more technical documentation.

Checkout only certain files

Jean-Francis Bastien — Wed, 02 Sep 2020 13:01:55 +0000

My Workflow

Bhacaz/checkout-files is useful to only pull specific files from a repository instead of the hold project with the well known actions/checkout. Some project can be very heavy to pull when what you need it’s just 2 or 3 files.

It can be useful if you only need package config files like package.json or Gemfile to setup a Github Action environment, since popular action like ruby/setup-ruby look for the .ruby-version to automatically determine which version to setup and the Gemfile.lock to install the right version of bundler. I personally use it along with an other script to run bundle outdated on a Ruby project. For more details have a look on my other post.

Automatically keep tracks of outdated gems in a Github Issue

Jean-Francis Bastien ・ Jun 9 '20

#ruby #github

Submission Category:

Wacky Wildcards. Because it's a very general action that can be use for multiple case.

Yaml File or Link to Code

Bhacaz / checkout-files

Github Action checkout only certain files

checkout-files

⚠️ Please consider using actions/checkout with the option sparse-checkout.

GitHub Action to checkout only certain files and/or folders Useful if only need certain files, like config or assets for your workflow, instead of pulling the whole repo.

Usage

Minimal setup.

- name: Checkout files
  uses: Bhacaz/checkout-files@v2
  with:
   files: package.json

Inputs

Name	Description	Required	Default
`files`	A list of files with the path separated by a space, relative to root of your repository. Can also be a folder and the action will recursively pull all the files.	`true`	N/A
`token`	A GitHub token.	`false`	`${{ github.token }}`
`branch`	Checkout files from a specific branch. If not specified, it use the default repository branch. To use the current working branch `${{ github.head_ref \|\| github.ref_name }}`	`false`	Default branch of the repository.

Limitations

This action doesn't keep the mode bits (or permission) of files. See #18 for…

View on GitHub

Additional Resources / Info

You can find an example of usage in this Ruby on Rails project of mine. Bhacaz/democraylist-be.github/workflows/outdated_gems.yml

Automatically keep tracks of outdated gems in a Github Issue

Jean-Francis Bastien — Tue, 09 Jun 2020 17:03:53 +0000

Long story short, in my organization, I'm responsible for upgrading our Rails application. First thing I checked was every gems that could be updated right away.

I quickly found the outdated command from bundler.

I ran it with the options --only-explicit --strict to check what is explicitly specified in my Gemfile and for what I can simply do bundle update <<gem> without changing the requested version in my Gemfile.

Without much of a surprise, we had more than 70 gems that could be updated right away.

To prevent being in a similar situation in a few months or years, I had the idea to run the 'bundle outdated' command automatically, so I can keep track of new gem release. My solution was to create a script that can run in a Github Action to keep a Github Issue updated with the list of all outdated gems and their newer versions. So now I can easily see many dependencies that can be updated.

How it works

You need to create a Github Action, it can be done by creating a .yml file under .github/workflows in your project. You will also need a Github private access token with the scope repo to be able to update the relative Github Issue. You can use the example in the README of the project.

In the example, the action runs on every push on master, which is convenient in a very active project and to have a live update of the issue if you merged an update. You can also choose to use a cron rule, which can be useful with a less active project.

When the action runs it will,

Setup a Ruby environment with the version you specified in the .yml file
Pull the script
Download the Gemfile and Gemfile.lock files from your project
Run the command bundle outdated --only-explicit --strict
Create or update the description of the associated issue

Bhacaz / bundler-outdated-action

Script to use in a Github Actions to list in a issue the outdated gems

bundler-outdated-action

Use Github Actions to create and update a Github issue with the gems in your project that can be updated.

The result look like this:

Outdated gems (4)

bundle outdated --strict

Gem	Current	Newest	Groups
byebug	11.1.1	11.1.3	development, test
figaro	1.1.1	1.2.0	default
sidekiq	6.0.6	6.0.7	default
web-console	4.0.1	4.0.2	development

To use

Create a new workflows in your project (.github/workflows/outdated_gems.yml)
Create a Personal access tokens with the scope repo
Add the token in the secrets of your repository with the name GH_TOKEN

Example:

name: 'Outdated Gems'
on:
  push:
    branches:
      - master

jobs:
  outdated_gems:
    runs-on: ubuntu-latest
    name: Outdated gems
    steps:
      - name: Checkout repo
        uses: actions/checkout@v4
      - name: Setup Ruby
        uses: ruby/setup-ruby@v1
      - name: 'Pull outdated gem action script'
        uses: actions/checkout@v4
        with:
          repository: 'Bhacaz/bundler-outdated-action

…

View on GitHub

Happy updating

A Slack Bot for your private Advent of Code Leaderboard

Jean-Francis Bastien — Thu, 05 Dec 2019 22:02:42 +0000

Slack Bot for the Advent of Code

In this festive time, a colleague created a private Leaderboard and invited every dev where I work to participate. I was very exited and after completing the first challenge I thought something was missing to engage others.

A Slack Bot that show the progress of every participants.

Thanks to this repo, tomswartz07/AdventOfCodeLeaderboard that gave me the idea.

I didn't want something that posted every 10 minutes with the same score. So I made a Rails app (because this's what I know) that will check if someone gained a ⭐️, save it and then send the new LeaderBoard.

Bhacaz / Advent-of-Code-Slack-Bot

Advent of Code Leaderboard bot

Advent of code Slack Bot

This is a Slack bot to post a Advent of code Private Leaderboard to a Slack channel when someone complete a challenge.

Prerequisites:

slack_url: An Incoming WebHooks url for workplace Slack.
slack_channel: The name of the channel you want to post the LeaderBoard
session: A cookie session token from Advent of Code. It can be find in a request header in the devtool of your browser.
leaderboard_id: The ID of your private Leaderboard. It can be found at the end of the url of your Leaderboardhttps://adventofcode.com/2019/leaderboard/private/view/<<XXXXX>>>

You can create a config/application.yml file to set those env variables

Running:

Run the Rails server bin/rails server
Create a cron job that will fire the Incoming WebHooks if someone recently complete a challenge every 10 minutes.

$ EDITOR=nano crontab -e

Add this line

*/10 * * * * curl http://localhost:3000/api/exec_webhook

Build on:

…

View on GitHub

Have a look and happy Advent of Code