michaelheap.com

Take a screenshot of a video using ffmpeg

2023-05-23T12:06:32Z

I needed to extract a frame at the same time for multiple videos (the title slide for a TV show) to help make sure that the filenames reflected the episode the file contained. ffmpeg made it super-easy.

To take a single screenshot:

bash
ffmpeg -ss 00:00:51 -i video.mp4 -frames:v 1 -q:v 2 output.jpg

To take a screenshot of all videos in a folder and name the output file based on the input file:

bash
for i in `ls`; do ffmpeg -ss 00:00:51 -i $i -frames:v 1 -q:v 2 /tmp/screenshots/$i.jpg; done

GitHub Scheduled Reminders

2023-05-22T08:32:31Z

I’ve always struggled to manage my GitHub notifications. Having them pushed to me in real-time is overwhelming, but having a separate inbox to check means that I never remember to look at them.

GitHub notifications can be separated in to two categories for me, periodic and real-time. Periodic are things that need doing, but not right now (a PR is ready to review, for example). Real-time are items where there is a real human interacting with you (someone’s commented or requested changes on your PR).

It turns out that GitHub launched scheduled reminders back in 2020 which is a great fit for this use case. Scheduled reminders allow you to receive reminders at specific times throughout the day in addition to real-time alerts for specific events. You can configure them for yourself, or for a specific GitHub team.

Personal reminders

Personal reminders are linked to your personal GitHub account. That means you configure them in your personal GitHub settings and receive them as a DM from the GitHub bot. Head to your GitHub settings to configure them. You’ll be presented with a list of organisations. Once you choose an org it will ask you to authorize a Slack workspace and configure the days/times that you'd like to be reminded.

I've found that 8:30am and 2:30pm on weekdays is a good schedule for me. It allows me to review PRs before getting back to focused work when I start my day / after lunch. I also enable review requests waiting on my team in addition to those that are assigned specifically to me. This takes care of the period reminders that there are still PR reviews outstanding.

The next thing to configure is real-time alerts. I try to focus on things that need immediate attention, which means I disable notifications when I'm assigned a review (I'll see it in the periodic reminders). Here are the alerts that I do enable:

I'd also like to enable "Your PR has failed CI checks" but it requires a list of failed check names. I'd love to see the ability to get notified on all check failures so that I can keep my open PRs moving.

Once you press "Create reminder" you'll see your selected reminder times and the connected Slack workspace on your reminders overview:

Team reminders

You can also configure team reminders in addition to personal reminders. The settings are a little bit different as team reminders don't allow for real-time alerts. They do however have more filters available to control which PRs are shown in the reminder.

To configure team reminders, head to https://github.com/orgs/YOUR_ORGKong/teams and select the team you'd like to receive reminders for. Click Settings in the top right, then Scheduled reminders on the left. You can configure multiple reminders, each going to a different channel. This is useful if you want to direct specific repos to specific channels.

The settings I always enable here are "Ignore drafts" and "Require review requests". This makes sure that only PRs that can be reviewed are in the list of reminders. If you use "require review requests", make sure that you use the CODEOWNERS file to trigger review requests for your team.

There are some other useful configuration options in here too:

Ignore approved pull requests - Only remind the team about PRs that have not yet been approved. I set this to "Ignore with 2 or more" as the PR requires approval from two teams
Minimum staleness - This controls how long a PR has to be inactive before you're reminded about it. We set this to 0 hours, but it could be useful if you want to see stale PRs.
Ignored labels - This is useful if your PR is awaiting changes from the author. You can add a waiting-for-author label (or use the Issue Management GitHub Action) and exclude any PRs that have that label
Required labels - The opposite of the entry above. Some of our PRs have a review scope (e.g. copyedit, tech or SME - that's subject matter expert) to indicate what we should be looking for. We use this option to push review:tech items to a separate channel as the audience for these PRs is much smaller.

What does it look like?

Once you've configured your reminders, you'll start to receive notifications in Slack. These notifications will be broken down by repository, and contain additional metadata such as how old the PR is and how long it's been inactive. Here are a couple of examples.

Example: Personal Reminders

Personal reminders will be sent to you via DM:

Example: Team Reminders

Team reminders will be sent to a specific channel:

If your team have linked their Slack and GitHub accounts, the notification will show their Slack handle rather than their GitHub handle:

Where should my content live? Docs or blog?

2023-05-13T13:09:59Z

It’s 4pm on Thursday and you’ve just wrapped up an awesome piece of content that you’ve been thinking about for over a month. You finally had time to sit down and build a demo and write down how you did it so that others can follow along too.

Then you hear the age old question:

Are you planning to publish this on our blog or in the documentation?

The question hits you like a ton of bricks. Not this again. You just wanted to write. To teach. Who cares where it’s published? Just publish it so that others can learn!

The thing is, where you publish your content is important. Let's take a look at when you'd choose to publish on your blog, and when to contribute to the documentation.

Choose the Blog

There are a couple of instances where content should definitely go on your blog rather than in your documentation:

It’s an announcement rather than something educational
It’s a fun extra that’s not really core to your business (e.g. “managing your infrastructure with Terraform”, where you just happen to deploy your product)
Niche but interesting technical content (e.g. how we diagnosed network performance issues on $cloud)
It’s something that you want to publish now, but not maintain forever. Publishing on a blog means that it has a published_at date. People don’t expect a blog post from 2017 to be accurate, and are a lot more forgiving. Some examples of when this is useful:
- Collaborations with other companies
- Using X with your product (where X is the flavour of the month, such as AI)
- Using X with Y, where newer versions make the instructions invalid
Anything that contains an opinion. This is typically your thought-leadership type content

If your content doesn’t fit in to any of the above buckets, you may choose to publish it on your blog anyway. This is typically the case when:

Your blog has much better SEO than your docs and you want people to find the content
The author’s personal style does not fit the rest of your documentation, but the content benefits from having a unique style
You’re trying to tell a story rather than educate someone. Blog posts can skip a lot of the prerequisites for a project and assume the reader knows enough to get started.

Choose the docs

When we publish documentation, we commit to it being accurate forever. We need to regularly revisit pages to ensure that the content is accurate for the current version (and potentially older versions too). It’s no longer a snapshot of a point in time. It’s a living thing that grows with your product.

It’s an easy decision to put things in the docs for me if any of the following are true:

You need to maintain the content indefinitely
It’s focused purely on the how rather than the why
It’s a step-by-step tutorial on how to achieve something with your product
It’s a reference document, such as an API specification or configuration reference
There are multiple code samples showing how to achieve a single task

You might also choose to put the content in the docs if:

The content is maintained by multiple people, follows standards and has a consistent tone of voice
It’s something that you need to send to customers. Being in the docs add’s an “official” feeling to the content

Help me decide

If you’re still not sure where to put your content, put in on your blog. It’s the lowest friction way to get started, and having the content somewhere is generally better than not having it at all.

Writing precise, organised, complete documentation takes time and effort. Writing a blog post takes time and effort too, but less so. People are more forgiving when it comes to transient content.

Once published, watch your analytics. If you see a blog post receiving consistent traffic, you should officially adopt the content and work it in to your documentation (at which point you’ll have the fun “what about our SEO” conversation where everyone’s too scared to move the content).

In summary

Use the blog for time-limited content. Use the docs for evergreen
Explain why on the blog, and how in the docs
Authors have a unique style on the blog. Content is uniform in the docs
If you’re sharing ideas, use the blog. If you’re educating, use the docs.
Finally, if there’s a risk the content won’t get published at all, just use the blog. It’s easier to move from the blog to the docs than it is to remove something from the docs later.

Carving the Turkey

2023-05-08T12:00:25Z

One of the things I learned early on in my DevRel career is that you’ve got to be creative when it comes to content production. Starting from scratch for every blog post, video or conference talk means that you can only produce 1-2 pieces of deep content per month.

Fortunately, I’ve worked with some great advocates that taught me how to “carve the turkey”. Just like there are lots of different cuts from a turkey, there are ways to get more out of a single piece of content.

An Abstract Workflow

I start each project with the intention to produce at least three pieces of content - internal documentation, a public blog post and a demo video about the feature. Many projects will lead to more pieces of content than this, but three is the minimum I aim for.

For larger projects, you might end up with live streams and a conference talk in addition to your documentation, blog post and videos. This all depends on the team you have and how much emphasis you’re putting on content

Here’s the process I go through when working through a project:

(Offline) Read the basics + build up a list of docs / cheat sheet to use later
(Live Stream, optional) Try out the things you’ve learned. Make mistakes, it’s ok! We’re all learning together at this point. These aren’t expected to be polished.
(Documentation) Write user facing documentation that combines the generic understanding of your topic with things that are specific to your business
(Blog Post) Write unique content about the topic. It could be something you struggled to understand, or an innovative application of the technology. It may or may not mention your product.
(Videos) Record short demo videos to show off the capabilities of your product. Try to explain both why and the how these things work. These can be used for multiple purposes (with some editing), including:
- Sales enablement
- Social media promotion
- Product capability videos on YouTube
- Documentation
(Conference Talk, optional) Take what you’ve learned and combine them in to a 20-40 minute conference talk. Here are a few suggested frameworks:
- Introduction to X
- A deep dive in to X
- X for Y Audience
- Extending X
- Real world X use cases

This follows a pattern that’s common across most of my projects:

Learn
Try
Document
Apply
Teach

It’s hard to imagine what the above might look like for your project if you’ve never done it before, so let’s take a look at a project that I’m currently working on.

A Real World Example

Context: I’m the product manager for Kong Ingress Controller for Kubernetes. As part of my role I’m learning about new Kubernetes APIs

I’m currently learning about the Gateway API in Kubernetes, which is an area that I’m not too familiar with. There’s a lot of reading involved, and a lot of testing things out to see how it actually works.

Here’s a rough list of things I need to do to be successful:

Read the Gateway API specification
- Understand the component parts
- What are the differences between the Gateway API and Ingress API?
Try out the most common parts of the Gateway API
- I think this is HTTPRoute and TCPRoute from prior conversations
Document how Gateway API works with Kong
- How to add a service and a route
- How to add an authentication plugin
Provide Gateway API examples for the top 5 Kong use cases
- Prebuilt demos for Sales Engineering org
Talking points for the sales team targeting Kubernetes accounts

Looking at the above list, I can start to think about what content I can produce for each stage:

	Personal	Marketing	Product	Sales
Read the Gateway API specification	Cheat sheet of components. Difference between Ingress and Gateway API	Blog post: Ingress vs Gateway API.
Try out the most common parts of the Gateway API		Live stream: Exploring the Gateway API. Blog post: An introduction to HTTPRoute, TCPRoute and UDPRoute.		Demo video: Switch from X to Kong in < 5 minutes
Document how Gateway API works with Kong			Documentation: Getting started with Kong and the Gateway API.
Provide Gateway API Examples		Demo video: Gateway API and Y (x5, top 5 use cases) - used for social	Product feedback: Experience of augmenting the Gateway API with vendor. Documentation: Gateway API and Y (x5, top 5 use cases) extensions	Demo video: Gateway API and Y (x5, top 5 use cases) - used for demonstrating capabilities
Talking points for sales targeting Kubernetes		Blog post: Removing vendor lock-in with the Gateway API. Blog post: OSS at Kong: Building the Kubernetes ecosystem	Documentation: Migrating from X to Y using the Gateway API.	Demo video: Gateway API and Y (x5, top 5 use cases)

That’s a lot of content for something that could have resulted in zero pieces of public facing material. It would have been easy to spend a week reading everything and making private notes. Instead, we’ve produced 13 pieces of content which help your team mates, your customers, and you!

After all, the best way to learn is to teach.

Obsidian - Daily Note + Random Review

2023-04-18T07:55:58Z

I’ve been dutifully collecting notes in Obsidian for a while now, but the idea of going through and cleaning them all up was daunting. There are hundreds of notes that are just copy/pasted from other sources, screenshots of interesting things or rough notes on a topic.

Then I was reading about how you can use Periodic Notes to generate daily notes in Obsidian when I stumbled across this post from Michelle Mac. It showed how you can generate a list of random notes based on a tag.

I use tags in the page front matter rather than inline hashtags, so I needed to rework the logic a little. I also don’t keep all my notes in the same “Evergreen” folder, so I needed different logic for the filename.

Here’s what I ended up with. It generates a list of three posts when it runs. If you want to use it, change the values in allowedTags to source whichever pages you need:

js
<%*
	const randomNotes = [];
	const allowedTags = ["stub", "unedited"];
    app.metadataCache.getCachedFiles().forEach(filename => {
	    let data = app.metadataCache.getCache(filename);
	    if (!data.frontmatter) {
		    return;
	    }
	    const tags = (data.frontmatter.tags || []).filter(t => allowedTags.indexOf(t) !== -1)
	    if (tags.length > 0) {
			const p = filename.split("/");
			const f = p[p.length-1].split(".md")[0];
			randomNotes.push(f);
	    }
	});
    var i = 0
    do {
        const randomIndex = Math.floor(Math.random() * randomNotes.length);
        tR += `- [[${randomNotes[randomIndex]}]]` + "\n"
        i++
    } while (i<3);
%>

Check permissions in a GitHub Actions workflow

2023-04-03T15:14:46Z

When working with GitHub Actions, you may want to check what relationship the person performing an action has to a repo before running a workflow. Public documentation on collaborators is scarce, so here’s what I’ve been able to work out so far.

There are two ways to check relationships: pull_request.author_association and the /repos/:org/:repo/collaborators/:user/permission endpoint.
pull_request.author_association returns an item from CommentAuthorAssociation, which is one of the following:
1. COLLABORATOR: Author has been invited to collaborate on the repository.
2. CONTRIBUTOR: Author has previously committed to the repository.
3. FIRST_TIMER: Author has not previously committed to GitHub.
4. FIRST_TIME_CONTRIBUTOR: Author has not previously committed to the repository.
5. MANNEQUIN: Author is a placeholder for an unclaimed user.
6. MEMBER: Author is a member of the organization that owns the repository.
7. NONE: Author has no association with the repository.
8. OWNER: Author is the owner of the repository.
The /repos/:org/:repo/collaborators/:user/permission endpoint returns the permissions that the provided user has on a repository. This is one of: read, write, admin

Author Association

The author association field is available in the default pull_request payload, which makes it useful if you don’t want to make an additional API call to figure out if an actor should be allowed to perform an action or not.

When interacting with an organization's repo, the pull_request.author_association value is different depending on if the actor is an external collaborator, an org member, or neither.

If the actor is neither an org member nor an external collaborator their author_association will be one of the following:

FIRST_TIMER: The actor has never contributed to any repository on GitHub before
FIRST_TIME_CONTRIBUTOR: The actor has never contributed to this repository before
CONTRIBUTOR: The actor has previously contributed to the repository

If the actor has been added as an external collaborator, their author_association will be COLLABORATOR, no matter which set of permissions they’ve been given. If they have read permissions, they’re a COLLABORATOR. If they have admin permissions, they’re still a COLLABORATOR.

Finally, if the actor is a member of the organization that owns the repository their author_association will be MEMBER. This is true whether they are an organization member or owner. In addition, their author_association will always be MEMBER regardless of the permissions they have on the repository. If they have read permissions, they’re a MEMBER. If they have admin permissions, they’re still a MEMBER.

The only other state that you might be interested in is OWNER. This state is not possible with organization owned repositories. It is only returned when a repository is owned by a specific user.

That leaves us with 2 unused states:

MANNEQUIN - Mannequins are created when source code and metadata are migrated from one source control platform to GitHub. If the user was not properly mapped to a GitHub account at the time of migration a placeholder mannequin is created. If you’re interested in seeing a mannequin, check out this issue.
NONE - I’m not sure how to trigger this as any actor is implicitly a FIRST_TIMER, FIRST_TIME_CONTRIBUTOR or CONTRIBUTOR

Finally, let’s talk about deleted users. Any deleted user actions are attributed to ghost, which is a GitHub owned account that “takes the place of user accounts that have been deleted 👻”

User Permissions

If you’re looking for more granularity than the data provided in author_association you can use the /repos/:org/:repo/collaborators/:user/permission endpoint to fetch which permission the actor has for this repo.

Note: You’ll need push permission on the repository to be able to use the endpoint above.

The possible values returned by this repository are as follows:

none - :repo is a private repository and the user has no permissions
read - The user has read or triage permissions, or :repo is a public repository and the user has no permissions
write - The user has write or maintain permissions
admin - The user has admin permission

The permission level provided is the same no matter how the permission is granted. The actor may be added as an external collaborator or to an organization team. As long as they have permission to the repository somehow, it will be returned via the endpoint above.

If you’d like to check a user’s permission in a workflow before performing a step, I recommend the Has Permission action.

Here’s an example from their README (with a small change to use github.token rather than a secret):

yaml
name: Action Sample Workflow
# Run workflow when a new pull request is opened
on: [pull_request]
jobs:
  check_user_permission:
    runs-on: ubuntu-latest
    name: A job to check user's permission level
    steps:
      # Check for write permission
      - name: Check user permission
        id: check
        uses: scherermichael-oss/action-has-permission@master
        with:
          required-permission: write
        env:
          GITHUB_TOKEN: $
      # Use the output from the `check` step
      - name: Run only if user has sufficient permissions
        if: steps.check.outputs.has-permission
        run: echo "Congratulations! Your permissions to access the repository are sufficient."
      - name: Run only if user has NOT sufficient permissions
        if: "! steps.check.outputs.has-permission"
        run: echo "Sorry! Your permissions are insufficient."

When to use each option

So, which should we use? It depends what you want to check.

pull_request.author_association should be used when you want to check the relationship between the person performing an action and the repository itself. It’s useful when you want to auto-approve workflows for people that have contributed in the past (CONTRIBUTOR) or for everyone in your organization (MEMBER).

yaml
steps:
  - name: Check access
    if: ${{ github.event.pull_request.author_association != 'CONTRIBUTOR' && github.event.pull_request.author_association != 'MEMBER' }}
    run: |
      echo "Event not triggered by a collaborator."
      exit 1

If you need to check for specific permissions, the /repos/:org/:repo/collaborators/:user/permission endpoint is the option to choose. This is useful when you work for an organization where only specific teams have write access to a repository and should be allowed to perform specific tasks.

If you’re not sure which to use, I’d recommend using the permission endpoint (via scherermichael-oss/action-has-permission) as it allows for more granular access controls than pull_request.author_association.

The TAPE Model for Content

2023-03-20T11:00:17Z

Content is a mainstay of many Developer Relations teams, but it can sometimes be tough to show the impact that you’re having. Content on your company blog can be instrumented and attributed well, but what about things like YouTube videos or recorded conference talks?

You can build out complex tracking systems with UTM parameters and short URLs, but there’s an easier way to understand how your content is being used. It all starts with your internal teams.

DevRel is typically a cost centre. There isn’t any revenue attributed directly to the team. The best way I’ve found to justify your existence (and yes, unfortunately this is a thing in every business) is to attach yourself to the revenue generating teams.

Serving your internal audience has two outcomes:

You support teams that drive new business. The sales team can link to your videos to show prospective customers the capabilities of your platform and how easy it is to use
You save time for existing teams, which means you’re saving $$$. Every proof of concept cycle that is 10% faster thanks to your demo videos is money that the business isn’t spending on Sales Engineers. Every support ticket that is replied to with a link to your content is time that an agent doesn’t have to spend writing a response.

In both of these cases you’re drawing a direct link between the content that you’re producing and the impact it has on the revenue or efficiency of the business.

This is where the TAPE model comes in.

TAPE stands for Trigger, Action, People, Examples.

Trigger: Why are we producing this content? What problems have we observed that we can help solve?
Action: What are we producing? Is this best presented in the documentation, as a blog post, as a video etc?
People: Who is asking for this? Not our end customers, but our internal stakeholders. Can we make other teams successful?
Examples: Where is this being used? Is your content being used to solve support tickets? Is it being used to prove we have certain capabilities during an RFP?

By matching the content you produce to pain points that internal teams are having you know that the content is going to resonate with at least one audience. This is your trigger, your reason for producing the content in the first place.

Understanding who’s going to consume your content helps you decide which action to take. A VP of infrastructure is more likely to scan a documentation page than watch a video. A developer at a Global System Integrator might be more at home with a 60 minute deep dive video on to how to write plugins for your system.

Aim to make friends by supporting the right people. If you’re working with the sales team, target enterprise sales reps rather than lower value digital customers. If you’re working with Sales Engineers, work with regional leads who can help evangelise the work you do more widely. Saying “I helped $VP with $TOP10 customer” is much more impactful than saying “I solved 10 loosely related support tickets”

Then finally, keep track of how your content is being used. Make a note every time someone links to one of your pieces of content in Slack. This could be a product manager asking how a feature built before they joined works. It could be someone from marketing asking how a new feature behaves so that they can position it correctly. Building up a list of examples allows you to show that not only did you identify an opportunity to support people internally, the content is being used repeatedly to help enable the rest of the business.

Examples

Alright, so what does that actually look like? Here are five examples to get you started.

Trigger: Product decision to deprecate a feature
Action: FAQ, migration recommendations
People: CPO, Support, Docs Team, Customer Success
Examples: CPO shares with internal teams. Support use with inbound tickets. Docs team write public facing docs. Customer Success proactively reach out to their customers to explain how to migrate.

Trigger: New feature released
Action: 3 minute demo video showing how it works
People: Product Manager, Product Marketing, Social Media Manager, Solutions Engineers, Sales
Examples: Product Manager / Product Marketing used in sales enablement. Social media used for a blog post. Solutions engineers used as a basis for their own demos. Sales used to show prospects the platform capabilities.

Trigger: Marketing campaign by competitor
Action: Rebuttal video showing off product capabilities
People: Product Marketing, Sales
Examples: Product Marketing builds battle cards using the information. Sales use the content to influence champions within a business.

Trigger: Difficult to run your OSS project on MacOS
Action: Work on README and improving error messages in the app
People: Engineering, Community, Support
Examples: Increased contribution velocity for engineering. A community develops around your project. Reduced support ticket volume for common use cases

Trigger: An event is looking for a speaker
Action: Write and present a talk
People: Marketing, Sales
Examples: Marketing run the event with good attendance to drive MQLs. Sales use the content to show off platform capabilities with potential customers.

Conclusion

Using internal triggers as your source of content ideas allows you to map your contributions to the goals of other teams. Many of these teams contribute directly to revenue, and if you make them successful it’s easy to show the impact you’re having on the business.

It might be tempting at this point to try to add some attribution directly to your team. You might negotiate that 2% of every sale where your material is used is attributed to your team.

This is a trap.

If you can claim 2% of every deal (and this is a high percentage), you need to do 100 deals worth $500,000 every single year to get $1 million in attribution. If you’re impacting 100 deals per year, chances are that you’ve got a large-ish team who are definitely costing more than $1 million per year.

Instead, focus on the relationships. People trust people. A VP saying “that DevRel team sure are awesome. They’ve cut our sales cycle by 2 weeks” is worth much more than 2% of a sale.

Filter Google Analytics report

2022-11-29T13:58:08Z

I'm trying out Radar to keep track of analytics at a glance. It's Google Analytics collection works great, but the way that we've set up Google Analytics the data for multiple sites ends up in the same property.

I wanted to filter the report to only traffic to a specific subdomain. It took me too long to work out that I needed a dimensionFilterClauses entry with the ga:pagePath (via the schema).

Here's how to filter your reports in case you (or I) need to do it in the future:

json
{
  "reportRequests": [
    {
      "viewId": "YOUR_VIEW_ID",
      "dateRanges": [
        {
          "startDate": "today",
          "endDate": "today"
        }
      ],
      "dimensions": [
        {
          "name": "ga:date"
        }
      ],
      "metrics": [
        {
          "expression": "ga:pageviews"
        }
      ],
      "dimensionFilterClauses": [
        {
          "filters": [
            {
              "dimensionName": "ga:pagePath",
              "operator": "PARTIAL",
              "expressions": ["docs.konghq.com"]
            }
          ]
        }
      ]
    }
  ]
}

Other things that may be useful:

Endpoint: https://analyticsreporting.googleapis.com/v4/reports:batchGet
Method: POST
Auth: Bearer [token]

Then transform the results using the following JS snippet:

javascript
const pageCount = Number(
  data.reports[0].data.totals[0].values[0]
).toLocaleString();

Upgrade from Winston 2 to 3 using colors

2022-10-23T11:39:59Z

I updated a project from Winston 2 to Winston 3 this morning and needed to make a few changes to how it was configured.

I previously created a logger instance, then switched to using syslog levels with a custom colour scheme. Here's how I did it in Winston 2:

javascript
var winston = require("winston");
var logger = new winston.Logger({
  transports: [
    new winston.transports.Console({
      level: "warning",
      colorize: true,
    }),
  ],
});
syslogColors = {
  debug: "rainbow",
  info: "cyan",
  notice: "white",
  warning: "yellow",
  error: "bold red",
  crit: "inverse yellow",
  alert: "bold inverse red",
  emerg: "bold inverse magenta",
};
winston.addColors(syslogColors);
logger.setLevels(winston.config.syslog.levels);

In Winston 3, the new winston.Logger call has been replaced with winston.createLogger, levels must be provided in the constructor, and formatting is handled by individual formatters using the logform library.

Here's how to achieve the same thing as above in Winston 3:

javascript
const winston = require("winston");
const syslogColors = {
  debug: "rainbow",
  info: "cyan",
  notice: "white",
  warning: "yellow",
  error: "bold red",
  crit: "inverse yellow",
  alert: "bold inverse red",
  emerg: "bold inverse magenta",
};
let format = winston.format.combine(
  winston.format.colorize({
    all: true,
    colors: syslogColors,
  }),
  winston.format.simple()
);
var logger = winston.createLogger({
  transports: [
    new winston.transports.Console({
      level: "warning",
      format,
    }),
  ],
  levels: winston.config.syslog.levels,
});

Running `gickup` on a QNAP NAS

2022-10-15T18:00:01Z

I learned about Gickup whilst reading Jeff Geerling’s backup plan and thought it would be a useful thing to run for my own repos.

I initially ran it on my local machine periodically, then realised that I could run it on my QNAP NAS every night. Here’s how I did it:

Create a shared folder named gickup to contain the backups. I’ve got a volume named Backups that contains this, but any volume will do
Create a directory to store your backups by running mkdir -p /share/gickup/repos
Edit /etc/config/crontab and add the following line to the end: 0 3 * * * docker run --rm -v /share/gickup:/hostvol buddyspencer/gickup:0.9 /gickup/app /hostvol/config.yml > /share/gickup/last-run.log 2>&1. This will run gickup every day at 3am
Reload cron to pick up that change by running crontab /etc/config/crontab && /etc/init.d/crond.sh restart

You may have noticed that I reference /hostvol/config.yml. I mount the /share/gickup folder a /hostvol, and config.yml is my gickup configuration file. Here’s what it looks like:

yaml
# config.yml in /share/gickup
source:
  github:
    - token: CHANGE_ME_TO_YOUR_GITHUB_PAT
      excludeorgs: # this excludes repos from the organizations "foo" and "bar"
        - foo
        - bar
destination:
  local:
    - path: /hostvol/repos
      structured: true

Create your own config.yml, making sure you change the token value. If you’ve configured all of the above, all the repositories you have access to will be backed up at 3am each day.